From 7bea58a3f4996c6faa445fa04dfd3938aaca3e61 Mon Sep 17 00:00:00 2001 From: Avigail Date: Thu, 11 Sep 2025 01:10:33 +0300 Subject: [PATCH 01/22] feat(alert): add pf-alert component and update package/config --- elements/package.json | 1 + elements/pf-alert/README.md | 131 ++++++++ elements/pf-alert/demo/alternate.html | 63 ++++ elements/pf-alert/demo/color-context.html | 15 + elements/pf-alert/demo/deprecated-states.html | 39 +++ elements/pf-alert/demo/dismissable.html | 59 ++++ elements/pf-alert/demo/index.html | 12 + elements/pf-alert/demo/inline.html | 55 ++++ elements/pf-alert/demo/states.html | 63 ++++ elements/pf-alert/demo/toast.html | 59 ++++ elements/pf-alert/docs/00-overview.md | 10 + elements/pf-alert/docs/10-style.md | 100 ++++++ elements/pf-alert/docs/20-guidelines.md | 267 +++++++++++++++ elements/pf-alert/docs/30-code.md | 188 +++++++++++ elements/pf-alert/docs/40-accessibility.md | 38 +++ .../pf-alert/docs/alert-a11y-focus-order.svg | 75 +++++ .../docs/alert-a11y-keyboard-interactions.svg | 85 +++++ .../docs/alert-guidelines-actions.svg | 123 +++++++ .../docs/alert-guidelines-behavior-1.svg | 110 +++++++ .../docs/alert-guidelines-behavior-2.svg | 68 ++++ .../alert-guidelines-best-practice-do.svg | 43 +++ .../alert-guidelines-best-practice-dont.svg | 31 ++ .../alert-guidelines-dismissible-inline.svg | 89 +++++ .../alert-guidelines-dismissible-toast.svg | 74 +++++ .../docs/alert-guidelines-layout-inline-1.svg | 32 ++ .../docs/alert-guidelines-layout-inline-2.svg | 143 ++++++++ .../docs/alert-guidelines-layout-toast.svg | 43 +++ ...-guidelines-responsive-large-screens-1.svg | 74 +++++ ...-guidelines-responsive-large-screens-2.svg | 43 +++ ...rt-guidelines-responsive-small-screens.svg | 159 +++++++++ .../docs/alert-guidelines-severity.svg | 304 ++++++++++++++++++ .../pf-alert/docs/alert-style-anatomy.svg | 72 +++++ .../pf-alert/docs/alert-style-spacing-1.svg | 108 +++++++ .../pf-alert/docs/alert-style-spacing-2.svg | 78 +++++ .../pf-alert/docs/alert-style-spacing-3.svg | 138 ++++++++ .../docs/alert-style-variant-inline-alt.svg | 54 ++++ .../docs/alert-style-variant-inline.svg | 63 ++++ .../docs/alert-style-variant-toast.svg | 67 ++++ elements/pf-alert/docs/screenshot.png | Bin 0 -> 2815 bytes elements/pf-alert/docs/screenshot.svg | 17 + elements/pf-alert/pf-alert-toast-styles.css | 48 +++ elements/pf-alert/pf-alert.css | 185 +++++++++++ elements/pf-alert/pf-alert.ts | 207 ++++++++++++ elements/pf-alert/test/pf-alert.e2e.ts | 12 + elements/pf-alert/test/pf-alert.html | 12 + elements/pf-alert/test/pf-alert.spec.ts | 116 +++++++ elements/tsconfig.json | 2 +- package-lock.json | 4 +- 48 files changed, 3776 insertions(+), 3 deletions(-) create mode 100644 elements/pf-alert/README.md create mode 100644 elements/pf-alert/demo/alternate.html create mode 100644 elements/pf-alert/demo/color-context.html create mode 100644 elements/pf-alert/demo/deprecated-states.html create mode 100644 elements/pf-alert/demo/dismissable.html create mode 100644 elements/pf-alert/demo/index.html create mode 100644 elements/pf-alert/demo/inline.html create mode 100644 elements/pf-alert/demo/states.html create mode 100644 elements/pf-alert/demo/toast.html create mode 100644 elements/pf-alert/docs/00-overview.md create mode 100644 elements/pf-alert/docs/10-style.md create mode 100644 elements/pf-alert/docs/20-guidelines.md create mode 100644 elements/pf-alert/docs/30-code.md create mode 100644 elements/pf-alert/docs/40-accessibility.md create mode 100644 elements/pf-alert/docs/alert-a11y-focus-order.svg create mode 100644 elements/pf-alert/docs/alert-a11y-keyboard-interactions.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-actions.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-behavior-1.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-behavior-2.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-best-practice-do.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-best-practice-dont.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-dismissible-inline.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-dismissible-toast.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-layout-inline-1.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-layout-inline-2.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-layout-toast.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-responsive-large-screens-1.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-responsive-large-screens-2.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-responsive-small-screens.svg create mode 100644 elements/pf-alert/docs/alert-guidelines-severity.svg create mode 100644 elements/pf-alert/docs/alert-style-anatomy.svg create mode 100644 elements/pf-alert/docs/alert-style-spacing-1.svg create mode 100644 elements/pf-alert/docs/alert-style-spacing-2.svg create mode 100644 elements/pf-alert/docs/alert-style-spacing-3.svg create mode 100644 elements/pf-alert/docs/alert-style-variant-inline-alt.svg create mode 100644 elements/pf-alert/docs/alert-style-variant-inline.svg create mode 100644 elements/pf-alert/docs/alert-style-variant-toast.svg create mode 100644 elements/pf-alert/docs/screenshot.png create mode 100644 elements/pf-alert/docs/screenshot.svg create mode 100644 elements/pf-alert/pf-alert-toast-styles.css create mode 100644 elements/pf-alert/pf-alert.css create mode 100644 elements/pf-alert/pf-alert.ts create mode 100644 elements/pf-alert/test/pf-alert.e2e.ts create mode 100644 elements/pf-alert/test/pf-alert.html create mode 100644 elements/pf-alert/test/pf-alert.spec.ts diff --git a/elements/package.json b/elements/package.json index 94dadf7fc8..7a6f35bf6c 100644 --- a/elements/package.json +++ b/elements/package.json @@ -15,6 +15,7 @@ "./pf-accordion/pf-accordion-header.js": "./pf-accordion/pf-accordion-header.js", "./pf-accordion/pf-accordion-panel.js": "./pf-accordion/pf-accordion-panel.js", "./pf-accordion/pf-accordion.js": "./pf-accordion/pf-accordion.js", + "./pf-alert/pf-alert.js": "./pf-alert/pf-alert.js", "./pf-avatar/pf-avatar.js": "./pf-avatar/pf-avatar.js", "./pf-back-to-top/pf-back-to-top.js": "./pf-back-to-top/pf-back-to-top.js", "./pf-background-image/pf-background-image.js": "./pf-background-image/pf-background-image.js", diff --git a/elements/pf-alert/README.md b/elements/pf-alert/README.md new file mode 100644 index 0000000000..07aadbbd78 --- /dev/null +++ b/elements/pf-alert/README.md @@ -0,0 +1,131 @@ +# Alert +An Alert is a banner used to notify a user about a change in status or communicate other information. It can be generated with or without a user triggering an action first. + +## Usage +An alert is used by wrapping html elements with an `rh-alert` element as slots in order to format the data in the desired manner. + +An alert consists of the following slots: + +`Header` +- Header text for the alert, appears at the top of the alert. + +`Actions` +- Buttons that can be used to perform an action from the alert, such as closing or accepting the alert. + +`Anonymous Slot` +- This is the text that is inserted into the state to be displayed in the main content body. + +An alert consists of the following attributes: + +`dismissable` +- The `dismissable` attribute adds a close button to the top right of the alert allowing the user to dismiss the alert. Clicking the close button dispatches a `close` event, then removes the alert from the page. + +An alert has the following events: + +`close` +- This is fired when the user clicks the close button enabled by the `dismissable` attribute. Cancelling the event prevents the alert from closing. + +## Installation + +If using npm/bundlers: +```bash +npm install @rhds/elements +``` + +Then once installed, import it to your application: + +```js +import '@patternfly/elements/pf-alert/pf-alert.js'; +``` +## Usage + +### Basic Alert + +```html + +

Default

+

Example Alert

+ Dismiss + Confirm +
+``` + +### Info Alert (also available `success`, `warning`, `danger`, and `error`) + +```html + +

Info

+

Example Alert

+ Dismiss + Confirm +
+``` + +### Inline Alert +```html + +

Default

+

Example Alert

+ Dismiss + Confirm +
+``` + +### Toast Alert + +Alerts may be toasted using the `toast()` function. A toasted alert has a +unique style, a drop shadow, and either disappears after eight seconds, or can persist until the user dismisses it. + +```js +import { PfAlert } from '@patternfly/elements/pf-alert/pf-alert.js'; + +await PfAlert.toast({ + heading: 'Toast alert', + message: 'Example toasted alert', + actions: [ + { variant: 'secondary', action: 'confirm', text: 'Confirm' }, + { action: 'dismiss', text: 'Dismiss' } + ], +}); + +``` + +You can respond to the various actions by listening for the `close` event + +```js +document.addEventListener('close', function(event) { + if (event.target instanceof PfAlert) { + switch (event.reason) { + case 'close': // handle alert close ("X" button) + case 'dismiss': // handle alert dismiss (data-action="dismiss") + case 'confirm': // handle alert confirm (data-action="confirm") + } + } +}); + +``` + +### Adding an Event Listener to a Basic Alert + +If you would like to add custom logic when the alert is closed, you can do so with JavaScript. +```js +// Query for the alert element +const alert = document.querySelector('pf-alert'); +alert.addEventListener('close', () => { + // Add code to be executed when the alert element is closed. +}); +``` + +### Preventing the default close behavior in a Basic Alert +```js +// Query for the alert element +const alert = document.querySelector('pf-alert'); +alert.addEventListener('close', async function (event) { + // Prevent the alert from closing + event.preventDefault(); + // Perform some async task + await alertClosed(); + // Close the alert when finished + this.remove(); +}); +``` diff --git a/elements/pf-alert/demo/alternate.html b/elements/pf-alert/demo/alternate.html new file mode 100644 index 0000000000..2ca469e941 --- /dev/null +++ b/elements/pf-alert/demo/alternate.html @@ -0,0 +1,63 @@ +
+ +

Neutral

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Info

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Success

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Warning

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Danger

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Caution

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+
+ + + + \ No newline at end of file diff --git a/elements/pf-alert/demo/color-context.html b/elements/pf-alert/demo/color-context.html new file mode 100644 index 0000000000..4d3d28c50a --- /dev/null +++ b/elements/pf-alert/demo/color-context.html @@ -0,0 +1,15 @@ + + +

Default

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+
+ + \ No newline at end of file diff --git a/elements/pf-alert/demo/deprecated-states.html b/elements/pf-alert/demo/deprecated-states.html new file mode 100644 index 0000000000..0e507819c0 --- /dev/null +++ b/elements/pf-alert/demo/deprecated-states.html @@ -0,0 +1,39 @@ +
+ +

Error - alias of Danger

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Dismiss + Confirm +
+ + +

Default - alias of Neutral

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Dismiss + Confirm +
+ + +

Note - alias of Info

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Dismiss + Confirm +
+
+ + + + \ No newline at end of file diff --git a/elements/pf-alert/demo/dismissable.html b/elements/pf-alert/demo/dismissable.html new file mode 100644 index 0000000000..f5eae98b35 --- /dev/null +++ b/elements/pf-alert/demo/dismissable.html @@ -0,0 +1,59 @@ +
+ +

Default dismissable

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Inline dismissable

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Toast dismissable

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Dismissable With Prevent Default

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+
+ + + + \ No newline at end of file diff --git a/elements/pf-alert/demo/index.html b/elements/pf-alert/demo/index.html new file mode 100644 index 0000000000..4deef30e64 --- /dev/null +++ b/elements/pf-alert/demo/index.html @@ -0,0 +1,12 @@ + +

Default

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + \ No newline at end of file diff --git a/elements/pf-alert/demo/inline.html b/elements/pf-alert/demo/inline.html new file mode 100644 index 0000000000..14c19e0b64 --- /dev/null +++ b/elements/pf-alert/demo/inline.html @@ -0,0 +1,55 @@ +
+ +

Default

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Info

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Success

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Warning

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Danger

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+
+ + + + \ No newline at end of file diff --git a/elements/pf-alert/demo/states.html b/elements/pf-alert/demo/states.html new file mode 100644 index 0000000000..82173fdcd0 --- /dev/null +++ b/elements/pf-alert/demo/states.html @@ -0,0 +1,63 @@ +
+ +

Danger

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Warning

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Dismiss + Confirm +
+ + +

Caution (mapped to Warning)

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Dismiss + Confirm +
+ + +

Neutral

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Info

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+ + +

Success

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est + egestas, a sollicitudin mauris tincidunt.

+ Confirm + Cancel +
+
+ + + + \ No newline at end of file diff --git a/elements/pf-alert/demo/toast.html b/elements/pf-alert/demo/toast.html new file mode 100644 index 0000000000..72f624b578 --- /dev/null +++ b/elements/pf-alert/demo/toast.html @@ -0,0 +1,59 @@ +
+
+ Alert State + + + + + + +
+
+ Persistence + +
+
+ Actions + + + +
+ Toast alert +
+ + + + \ No newline at end of file diff --git a/elements/pf-alert/docs/00-overview.md b/elements/pf-alert/docs/00-overview.md new file mode 100644 index 0000000000..1d617e8e93 --- /dev/null +++ b/elements/pf-alert/docs/00-overview.md @@ -0,0 +1,10 @@ +## When to use + + - Communicate essential information in a prominent way + - Notify a user of a change in status + - Communicate urgency using severity + +
+ Two examples of the alert element +
diff --git a/elements/pf-alert/docs/10-style.md b/elements/pf-alert/docs/10-style.md new file mode 100644 index 0000000000..002becf31b --- /dev/null +++ b/elements/pf-alert/docs/10-style.md @@ -0,0 +1,100 @@ + + +## Style + +An alert is a layout including an icon, title, text, actions, and a close +button. It comes in a variety of colors depending on status. A toast is a +variant of alert. Instead of having a background color, it has a white +background with a drop shadow. + +### Anatomy + +
+ + Alert with numbers pointing to parts of the element + +
+ +1. Status icon +2. Title +3. Body text +4. Action buttons +5. Close button +6. Color background +7. White background with drop shadow + +
+
+ +## Variants + +### Inline + +The default alert is inline. At minimum, the status icon and title need to be visible. + + + Two examples of an inline alert + + +### Inline alternate + +There is an alternate inline alert where the border covers all sides. + + + Two examples of an alternate design for inline alerts + + +### Toast + +Same as the inline alert, at minimum, the status icon and title need to be visible. + + + Two examples of a toast alert + + +## Space + + + Diagram of spacing for inline alerts + + + + Diagram of spacing for toast alerts + + + + Diagram of spacing for alerts on mobile + + +## Interaction states + +Refer to these documentation pages for interaction states: + +- [Button](/elements/button/style/#interaction-states) diff --git a/elements/pf-alert/docs/20-guidelines.md b/elements/pf-alert/docs/20-guidelines.md new file mode 100644 index 0000000000..bae101a5c9 --- /dev/null +++ b/elements/pf-alert/docs/20-guidelines.md @@ -0,0 +1,267 @@ +## General guidelines + +In general, use an alert to communicate essential information to a user in a prominent way. + +### When to use an inline alert + +Use an inline alert to communicate a short message about a specific user action within a component or layout. An inline alert appears in a content area and disappears when a user closes it or navigates away from the page. For example, use an inline alert to inform a user their form was submitted with errors. + +### When to use a toast alert + +Use a toast alert to communicate a time-based update, confirmation, or other short message to a user without blocking their workflow. A toast alert overlays content in the top right corner of a page and disappears when a user closes it or when it times out. For example, use a toast alert to inform a user their information was submitted successfully. + +## Status levels + +The status levels for alerts are Neutral, Info, Success, Warning, Caution, and Error. Each level communicates a specific message or severity. + + +

Helpful tip

+

Go to the Color page to learn more about using status levels.

+
+ + + Examples of the different colors indicating alert status + + +### Dismissal + +Depending on the message, an inline alert can be dismissible or not dismissible. The close button should not be included if it is critical that a user read or interact with the alert. A toast alert is always dismissible. + + + Alert element dismissal inline examples + + + + Alert element dismissal toast examples + + +## Writing content + +Both alert variants have limited space. Therefore content should be short and concise. A user should be able to quickly scan the content and know what steps to take next. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementCharacter countHow to write
Title text60 +
    +
  • Short and descriptive
  • +
  • Try to communicate the primary message using only title text
  • +
  • Must communicate severity
  • +
  • Write fewer words if there is body text
  • +
  • Write more words if there is no body text
  • +
+
Body text150 +
    +
  • Write 1 - 2 concise sentences and include links if necessary
  • +
  • Be concise and explain how to resolve an issue
  • +
  • Optional if title text accurately communicates the message
  • +
+
Action text20 per button +
    +
  • Write 1 - 3 short words
  • +
  • Clearly write an action that a user can take
  • +
  • No long words or phrases
  • +
+
+
+ +## Actions + +Actions enable a user to perform a specific action in relation to the alert message. Both alert variants may include actions, but no more than two. Actions require using specific elements, however including actions is optional. + +- Primary action - use the [Secondary button](/elements/button/guidelines/#variants) element +- Secondary action - use the [Link button](/elements/button/guidelines/#variants) element + + + Example of button action text + + +## Layout + +### Inline + +An inline alert appears at the top of a content area or close to an item needing attention. The width varies based on content and layout. They can expand to fill a container or related content area. + + + Example of an inline alert at the top of a layout + + + + Example of an inline alert inside a form + + +### Toast + +A toast alert slides in from the top right corner of a page and then disappears when a user closes it or when it times out. A toast alert can be set as persistent or temporary depending on the message. + +- Persistent - does not disappear unless dismissed by a user +- Temporary - disappears after eight seconds unless dismissed by a user first + + + Toast alert with a link in the body text includes a close button + + +Content authors should avoid writing toast alerts in HTML, and instead use the +`toast()` JavaScript method to toast alerts, which handles the grouping, +animations, persistence, and other necessary features of the toasted alert +pattern. + + + + +```js rhcodeblock +import { RhAlert } from '@rhds/elements/rh-alert/rh-alert.js'; + +RhAlert.toast({ + state: 'caution', + message: 'Toast alerts using JavaScript', +}); +``` + + + +Use the JavaScript API to toast alerts. + + + + + + +```html rhcodeblock + +

Writing toasted alerts explicitly in HTML

+
+``` + +
+ +Write toast variant alerts in HTML. + +
+ +For more information on how to toast alerts using JavaScript, +please read the [code page][codepage]. + +## Behavior + +### Stacking + +When multiple toast alerts appear one after the other, they stack. The most recent alert appears at the top and pushes the rest down. When an alert disappears, the rest will fill the empty space. + + + Three toast alerts are stacked in the top left corner of a layout + + + + Only one toast alert in the stack from the previous image is left + + +## Responsive design + +### Large screens + +On large screens, inline alert height is determined by the amount of content included. Inline alert width is determined by the width of its container or related content area. Toast alert height is also determined by content, but its max width is 480px. + + + Example of inline alert spanning content column width + + + + + Example of a toast alert at content width + + +### Small screens + +On small screens, both alert variants will span one column, and toast alerts will continue to stack. + + + Example of toast and inline alerts span full column of small screen layout + + +## Best practices + +### Mixing use cases + + + + Example of using correct variants + + +

Use the correct alert variants for the correct use cases.

+
+ + + + Example of using incorrect variants + + +

Do not use an inline alert for toast alert use cases and vice versa.

+
+ +[codepage]: ../code/#toasting-alerts diff --git a/elements/pf-alert/docs/30-code.md b/elements/pf-alert/docs/30-code.md new file mode 100644 index 0000000000..63ac6c1b8f --- /dev/null +++ b/elements/pf-alert/docs/30-code.md @@ -0,0 +1,188 @@ +## Toasting Alerts +The `toast` variant of alert is intended specifically and only to be used when +toasting alerts. To toast an alert, use the static `toast()` method on the +`RhAlert` constructor. [Avoid](../guidelines/#toast) writing your own +`` in HTML. The argument to `toast()` is an object +with at least a `message` property, and several other options. + +```js rhcodeblock +import { RhAlert } from '@rhds/elements/rh-alert/rh-alert.js'; + +RhAlert.toast({ state: 'success', message: 'Saved!' }); +``` + +The full list of options for the `toast` method is: + + + +| Option | Type | Description | +| -------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- | +| `message` (required) | lit-html renderable value | Alert body content. Can be any value which lit-html can render. Simple strings are preferable | +| `heading` | `string` | Alert heading content. Must be a simple string. | +| `state` | See alert's `state` attribute | Alert `state` attribute | +| `persistent` | `boolean` | Whether the alert should remain on screen until the user explicitly dismisses it | +| `actions` | Array of one or two actions objects | One or more optional body actions. See [actions options](#toast-action-options) info below. | + + + +### Toast action options + +Actions objects have two keys, `text` for the action button text, and `action` +e.g. `dismiss` or `confirm`, which is applied to the `close` event as the +`action` property. + + + +| Option | type | Description | +| -------- | ------ | ------------------------------------------------------ | +| `text` | string | Button label text, e.g. "Confirm" | +| `action` | string | `close` event `event.action` property e.g. `'confirm'` | + + + +### Toasted alert content + +When toasting, you must provide body content for the alert. This content can +either be a string, a DOM node, a lit-html `TemplateResult`, or an array of the +same. + +#### Toasting a string + +```js rhcodeblock +await RhAlert.toast({ + message: 'Your request was submitted', +}); +``` + +#### Toasting a DOM Node + +```js rhcodeblock +const message = document.createElement('strong'); + message.textContent = 'Your request was submitted'; +await RhAlert.toast({ message }); +``` + +#### Toasting a lit-html template: + +```js rhcodeblock +import { html } from 'lit'; +await RhAlert.toast({ + message: html`Your request was submitted`, +}); +``` + +#### Toasting an array of renderables + +```js rhcodeblock +import { html } from 'lit'; +await RhAlert.toast({ + message: [ + 'Your request was', + html`successfully`, + new Text('submitted'), + ], +}); +``` + +You may, for example, use the `