Alert banner RFC

[loredanaspataru]

Alert banner

Alert banners show pressing and high-signal messages, such as system alerts. They're meant to be noticed and prompt users to take action.

Spectrum docs | Spectrum CSS

Usage

Add your dependency via:

yarn add @spectrum-web-components/alert-banner 

Import the side-effect registration of :

import ‘@spectrum-web-components/alert-banner/sp-alert-banner.js`;  

When looking to leverage the AlertBanner base class as a type or for extension purposes, do so via:

import { AlertBanner } from ‘@spectrum-web-components/alert-banner`;  

Examples

The alert banner accepts text context in the default slot provided:

<sp-alert-banner open> 
    All documents in this folder have been archived 
</sp-alert-banner> 

Use the action slot for the contextual action that a user can take in response to the issue described:

<sp-alert-banner open> 
    Your trial has expired 
    <sp-button slot=”action” variant=”secondary”> 
        Buy now 
    </sp-button> 
</sp-alert-banner>

Properties and attributes

Property	Attribute	Type	Default	Description
open	open	boolean	false	Show the alert banner when open is true
dismissible	dismissible	boolean	false	Whether to include an icon-only close button to dismiss it
variant	variant	AlertBannerVariant	neutral	Applies specific styling when set to neutral, informative or negative

Slots

• default slot for the text content
• action for the button element that surfaces the contextual action that a user can take (no more than one button in an alert banner)

Events

• close announces that alert banner has been closed

Behavior

Closing the alert banner

Since alert banners should be used for system-level messages, Spectrum’s guidelines advise that they should be dismissed only as a result of a user action or if the internal state that triggered the alert has been resolved.

This means that we don’t need to add a timeout for auto dismiss as we do for Toast (source: https://spectrum.adobe.com/page/alert-banner/#Dont-let-alert-banners-time-out).

As such, the alert can be dismissed externally by triggering the contextual action button or the close button in case of a dismissible alert. Internally, we can control the opened/closed state by using the open attribute and a public close method.

Transition

I haven’t found any guidelines in Spectrum on the transition animation for showing the alert banner. The initial idea was to use a fade-in/fade-out transition, similar to what the toast component does.

However, after the initial review, we decided to confirm with the design team what’s the expected behavior for showing/hiding the alert banner. We are still waiting for an answer on this. One option is to scope out the transition from the initial implementation and add that later after the requirement here is clear from a design perspective.

Responsive behavior

When the text is too long for the available horizontal space, it wraps to form another line.

In actionable alert banners, the button moves below the text prior to text wrapping.

Accessibility

Focus behavior

The alert-banner content div will be assigned the WAI-ARIA alert role, similar to Toast's markup, to inform screen readers and notify users accordingly. This was confirmed with the a11y team, the reason being that, for actionable alerts, we may not want screen readers to announce the action label along with the alert message.

As specified on W3C alert pattern, the component should not interfere with the user’s current workflow by changing page focus.

The alert banner supports keyboard interaction as follows:

• Tab should place focus on the next interactive element, which can be either the actionable button or the close button.
• Tab + Shift should place focus on the previous interactive element.
• Space or Enter should trigger the interaction if one of the buttons is focused, thus dismissing the alert in case of the close button or triggering the corresponding contextual action.
• Esc will dismiss an alert banner if it’s a dismissible alert.

Internationalization

For RTL languages, the layout of the alert banner is mirrored. The icon is right-aligned and the close button is left-aligned. If the alert banner is actionable, the button appears on the left side.

Customization

The current Spectrum design includes a divider and the initial thought was to make that optional. We confirmed that in Spectrum 2’s design, the divider was removed. As such, we won’t include the divider either in our current implementation.

Some consumers need new variants besides the ones defined by Spectrum: notice, premium and each of these has a subdued variant. We can use an attribute for subdued to express the changes in style between the variant and its subdued version (similar to how static and treatment change the button’s styling).

To allow adding new variants in an SXAlertBanner component that extends from AlertBanner we could add a protected method isValidVariant on the AlertBanner class that can be overridden by the class extension. Then, we can use the CSS –mod custom properties to apply the specific styling needed.

[najikahalsema]

This looks great! Thank you for your super detailed RFC!