<bliss-alert>

<bliss-alert> provides a messaging mechanism for alerting and informing.

• Installation
• Usage
  • Properties
• Contributing
  • Demoing with Storybook
  • Testing
  • Committing
  • Opening a merge request
• Troubleshooting

📦 Installation

To install this component, run:

yarn add @bliss-design-system/alert

🏎 Usage

To use this component, you'll need to register the component to the window's Custom Elements Registry. In order to achieve that, you'll want to call this function within your application's client-facing entry file:

import { blissRegisterAlert } from '@bliss-design-system/alert';

blissRegisterAlert(); // Registers <bliss-alert>

That will make the component available in your application. Additionally, you'll need to have the <bliss-button> component, the <bliss-icon> component, and the Iconsets registered to your application. All three are peer dependencies of this component, and you won't be able to see the icon or the close button without them.

With all of the setup you can use it like this:

<!-- Renders a small alert, with no heading and no close button -->
<bliss-alert>
  <p>Lorem ipsum <strong>dolor sit amet</strong>, consectetur adipiscing elit. <a href="#">Feugiat in viverra</a> lacus, volutpat vitae.</p>
</bliss-alert>

To use the alert with a heading, you'll need to provide a heading attribute and ensure the size is set to medium.

<!-- Renders a medium alert, with a heading and no close button -->

<bliss-alert size="medium" heading="Important heading">
  <p>Lorem ipsum <strong>dolor sit amet</strong>, consectetur adipiscing elit. <a href="#">Feugiat in viverra</a> lacus, volutpat vitae.</p>
</bliss-alert>

To use the alert with a different theming options, change the icon or make the alert dismissible, please look into the attributes available to this component.

<!-- Renders a medium warning-themed alert, with a heading and no close button -->
<bliss-alert theme="warning" size="medium" heading="Important heading">
  <p>Lorem ipsum <strong>dolor sit amet</strong>, consectetur adipiscing elit. <a href="#">Feugiat in viverra</a> lacus, volutpat vitae.</p>
</bliss-alert>

You can also make an alert dismissible by setting the dismissible attribute.

<!-- Renders a small warning-themed alert, with no heading and a close button -->
<bliss-alert theme="warning" dismissible>
  <p>Lorem ipsum <strong>dolor sit amet</strong>, consectetur adipiscing elit. <a href="#">Feugiat in viverra</a> lacus, volutpat vitae.</p>
</bliss-alert>

The alert's icon is customisable as well, as long as the icon you choose is available within the Iconset

<!-- Renders a small alert with a rocket icon, with no heading and no close button -->
<bliss-alert icon='rocket'>
  <p>Lorem ipsum <strong>dolor sit amet</strong>, consectetur adipiscing elit. <a href="#">Feugiat in viverra</a> lacus, volutpat vitae.</p>
</bliss-alert>

Properties

The component accepts the following properties:

| Property | Type | Description | Default | Required | Options | | --------------- |:--------------:| :-----------------------------:|:----------:|:--------:|:-------------------------:| | heading | string | defines the alert's heading | - | false | | | icon | string | defines the alert's icon | info | false | Any icon within the Bliss Iconsets | | size | string | defines the alert size | small | false | small, medium | | theme | string | alert theme | default | false | default, neutral, positive, notice, warning, critical | | close-text | string | alert close button label | Close | false | - | | dismissible | boolean | adds dismiss button to alert | false | false | true, false |

Accessibility

The <bliss-alert> handles the fundamental accessibility concerns for you. Based on the theme you choose, <bliss-alert> will add the appropriate status attribute.

• The critical theme will set aria-live="assertive" (used to provide the user with important, and usually time-sensitive, information, and often to tell the user an element has been dynamically updated)
• All other themes will set aria-live="polite" (advisory information for the user that is not important enough to justify an alert)
• The alert uses the heading to set the content of aria-labelledby and the message to set aria-describedby.

🫕 Contributing

If you'd like to contribute, please open an issue with your suggested change on our Proposal Board. Once that is accepted, either the Bliss team will work on it or you can make changes locally by doing the following:

# Clone this repository
git clone https://gitlab.com/bliss-design-system/components.git

# Move into the component toolkit
cd components/

# Install the dependencies
yarn

You don't need to move into the package's directory to run storybook, tests or anything else. All of those commands exist in the root of the component toolkit, so while you can work on the component within its specific folder, you don't need to move through directories to run anything.

Demoing with Storybook

You can see all of your changes as you make them on Storybook.

To run a local instance of Storybook for this component, run:

yarn storybook

Testing

If you want to test as you develop, run:

yarn test

// or

yarn test:watch

Committing

We follow the Conventional Commits specification, meaning that you'll be prompted to fill out a descriptive message when you commit. We also use these commits to manage our releases, so we appreciate details.

As a guideline for this component, we use:

• fix for bug fixes, minor stylistic improvements, etc.
• feat for any backward compatible API changes.

For anything that breaks backwards compatibility or introduces significant changes that require a major version change, please get in touch with the team.

Opening a merge request

When you're ready to open a merge request, please use a descriptive title and fill out the provided template.

The team will be notified, but it helps to post your merge request in #bliss_support.

🙃 Troubleshooting

We'll fill this section out as we go and as issues are raised. But if you haven't found what you're looking for, get in touch via [email protected] or via the #bliss_support Slack channel ✨.