Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds content to alert group react examples. #7763

Merged
merged 6 commits into from
Sep 7, 2022
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -6,37 +6,68 @@ propComponents: ['Alert', 'AlertGroup', 'AlertActionCloseButton', 'AlertActionLi
---

## Examples

### Variant examples

Alert groups utilize the same variants that are available to [alert components](components/alert/). You can add multiple alert variants to each group.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

### Static alert group
These alerts appear on page load and are discoverable from within the normal page content flow, and will not be announced individually/explicitly to assistive technology.

Static alert groups appear when the page loads. They are seen within the normal page content flow. They will not be announced individually or explicitly to assistive technology.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="./AlertGroupStatic.tsx"
```

### Toast alert group
Alerts asynchronously appended into dynamic AlertGroups with `isLiveRegion` will be announced to assistive technology at the moment the change happens, following the strategy used for aria-atomic, which defaults to false. This means only changes of type "addition" will be announced.
### Toast alert groups

Toast alerts appear in groups on top of content at the top right of the page. Click the buttons in the example below to simulate toast alerts on this webpage.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

Alerts that are asynchronously appended into dynamic `AlertGroups` with `isLiveRegion` will be announced to assistive technology at the moment the change happens, following the strategy used for `aria-atomic`, which defaults to `false`. This means only changes of type `addition` will be announced.

```ts file="./AlertGroupToast.tsx"
```

### Toast alert group with overflow capture
After a specified number of alerts displayed is reached, we will see an overflow message instead of new alerts. Alerts asynchronously appended into dynamic AlertGroups with `isLiveRegion` will be announced to assistive technology at the moment the change happens. When the overflow message appears or is updated in AlertGroups with `isLiveRegion`, the `View 1 more alert` text will be read, but the alert message will not be read. screen reader user or keyboard user will need a way to navigate to and reveal the hidden alerts before they disappear. Alternatively, there should be a place that notifications or alerts are collected to be viewed or read later. In this example we are showing a max of 4 alerts.
### With overflow capture

After a specified number of alerts displayed is reached, users will see an overflow message instead of new alerts. In the following example, an overflow message will appear when more than four alerts are queued.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="AlertGroupToastOverflowCapture.tsx" isBeta
```

### Singular dynamic alert group
This alert will appear in the page, most likely in response to a user action.
### Dynamic alert groups

Dynamic alerts are generated after the page initially loads. Additional measures are required to ensure these alerts are accessible to screen readers.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

**Singular dynamic alert groups**

These alerts will appear within the page, most likely in response to a user action.

```ts file="./AlertGroupSingularDynamic.tsx"
```

### Singular dynamic alert group with overflow message
This alert will appear in the page, most likely in response to a user action. In this example we are showing a max of 4 alerts.
**With overflow message**

In the following example, there can be a max of four alerts shown at once, based on the value of `maxDisplayed`. If there are more than the set maximum of alerts on a page, an overflow message will appear, which users can click on to see the full list of alerts. You may adjust the maximum number of allowed alerts as needed.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

Alerts asynchronously appended into dynamic alert groups with `isLiveRegion` will be announced to assistive technology at the moment the change happens. When the overflow message appears in an `AlertGroup` with `isLiveRegion`, the "view 1 more alert" text label will be read, but the alert message will not be read.

Screen reader and keyboard users will need a way to navigate to and reveal the hidden alerts before they disappear. Alternatively, there should be a place where notifications or alerts are collected to be viewed or read later.

```ts file="AlertGroupSingularDynamicOverflow.tsx" isBeta
```

### Multiple dynamic alert group
These alerts will appear in the page, most likely in response to a user action.
**Multiple dynamic alert group**

You may generate multiple alerts within a group at once in response to a user action. The following example adds three alerts per button click.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="./AlertGroupMultipleDynamic.tsx"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a followup, I think this example and the "Async alert group" example could be updated to be non-toast. This relates to my general comment made as part of the review.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the "async alert group" example - is that only relevant for non-toast? When I turn async on, alerts are added to the queue when I click both the toast alert and inline dynamic generators, but is it only intended for the inline dynamic/non-toast in practice?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@edonehoo I think that example could be relevant for toast or non-toast, but I don't think we need to show it for both types. This comment was more related to my second point in the first message about a possible flow of examples (Static Alert Group > Dynamic Alert Group > Toast Alert Group). Though it may be better to just mention in the example description how an "async alert group can be applied to both non-toast and toast alert groups" or something along those lines.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mcarrano do you know if the original intent for the Async alert group example was for it to only apply to toast alerts? Looks like when the component was first created that example was a toast group from the beginning, but I'm wondering if that was purposeful or just a choice made in the moment.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do think it was by intent. Toast alerts are asynchronous by nature. For inline alerts, sure, you could insert and remove inline alerts within a page dynamically, but I don't recommend that in most cases. The inline alerts usually come as the result of a submit operation or page refresh. Otherwise I think it can be a jarring user experience.


### Async alert group
This shows how an alert could be triggered by an asynchronous event in the application. Note how you can customize how the alert will be announced to assistive technology. See the alert group accessibility tab for more information.

This example shows how an alert could be triggered by an asynchronous event in the application. You can customize how the alert will be announced to assistive technology via the `aria-live` property. Click the "start async" alert button below and then click the alert generator buttons in other examples to demonstrate how this may work in practice. Click the "stop async alerts" button to halt this behavior.

See the alert [group accessibility tab](components/alert-group/accessibility) for more information on the customization options.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="./AlertGroupAsync.tsx"
```