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.

Sign up for GitHub

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

Jump to bottom

docs(migration): add Notification migration docs, update a11y info #2592

Merged
merged 3 commits into from
Oct 25, 2021
Merged

docs(migration): add Notification migration docs, update a11y info #2592

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
81eac8c
docs(migration): add Notification migration docs, update a11y info
tay1orjones Oct 22, 2021
6446043
Update src/pages/migrating/guide/develop.mdx
tay1orjones Oct 25, 2021
5feae47
Update src/pages/migrating/guide/develop.mdx
tay1orjones Oct 25, 2021
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
15 changes: 10 additions & 5 deletions src/pages/components/notification/accessibility.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,16 @@ users than the`role="status"`or`role="log"`. In either case, these notifications
attract the user’s attention without receiving focus to communicate the message.

Details pertaining to these roles include specifics around containing
interactive elements, focus behavior, and close behavior. The `role` of
`status`, `log`, and `alert` can not contain interactive elements, should not be
given focus, and can optionally be closed by pressing the `Escape` key. The
close button is given `aria-hidden="true"` so it is ignored by assistive
technologies.
interactive elements, focus behavior, close behavior, and semantic contents. The
`role` of `status`, `log`, and `alert` can not contain interactive elements,
should not be given focus, and can optionally be closed by pressing the `Escape`
key. The close button is given `aria-hidden="true"` so it is ignored by
assistive technologies. Generally, plain text is preferred to be used within
these notifications. When read by screenreaders, any semantic meaning
surrounding the contents is not reflected to the user. For instace - Bold or
italic emphasis, and/or semantic elements such as `<li>` etc. are not read to
the user. If semantics are included, it should be non-essential to the
understanding or meaning of the contents.

Notification components are allowed interactive children (actions) though, and
when an interactive element is provided, a `role="alertdialog"` is used. These
Expand Down
78 changes: 77 additions & 1 deletion src/pages/migrating/guide/develop.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ possible by detailing all of the updates below.
| Icons `size` prop | <Tag type="cyan">Breaking</Tag> | [Icons size prop](#icon-size-prop) | `@carbon/react/icons` `@carbon/icons-react` All icons |
| Component `className` prop | <Tag type="cyan">Breaking</Tag> | [CSS Grid](#css-grid-breaking) | `@carbon/react` |
| Event handlers | <Tag type="cyan">Breaking</Tag> | [CSS Grid](#css-grid-breaking) | `@carbon/react` |
| Notification | <Tag type="cyan">Breaking</Tag> | [CSS Grid](#css-grid-breaking) | `@carbon/react` |
| Notifications | <Tag type="cyan">Breaking</Tag> | [Notifications](#notifications-breaking) | `@carbon/react` |
| Tooltip | <Tag type="cyan">Breaking</Tag> | [CSS Grid](#css-grid-breaking) | `@carbon/react` |
| ContentSwitcher | <Tag type="cyan">Breaking</Tag> | [CSS Grid](#css-grid-breaking) | `@carbon/react` |
| Layer Component | <Tag type="cyan">Breaking</Tag> | [Layering](#layer-component-breaking) | Components using `light` prop |
Expand Down Expand Up @@ -664,3 +664,79 @@ Learn more about our Popover component and it's API below:
</ResourceCard>
</Column>
</Row>

## Notifications <Tag type="cyan">Breaking</Tag>

We have updated the notification components to be more accessible out of the
box. `ToastNotification` and `InlineNotification` now have `role="status"` by
default with additional `role` options of `log` and `alert`. These components do
not receive focus and should be used for information-only use cases. These
components no longer accept actions or interactive children.

For notifications requiring an action, a new `ActionableNotifiation` component
is available. It has a `role="alertdialog"` and recieves focus by default.
Automatic placement of focus can be turned off via the new `hasFocus` prop.

All notifications have a new optional `closeOnEscape` prop, it enables
notifications to closed by pressing the `escape` key. For more details, see the
[notification components accessibility page](https://v11.carbondesignsystem.com/components/notification/accessibility).

### What this means for you and your team

- Notifications will be WAI-ARIA compliant out of the box without the explicit
need for additional functionality or configuration

### How to migrate

#### Update `ToastNotification` usage

- The `title`, `subtitle` and `caption` props have been removed. Compose
notification contents using `children` instead.
- `children` can no longer contain interactive elements. A `ToastNotification`
containing an action or interactive children should be replaced with
`ActionableNotification`.
- The `notificationType` prop is no longer needed and can be removed.
- The default `role` is now `status`. `log` and `alert` can also be used.
- The `closeOnEscape` prop toggles the closing of notifications via the `escape`
key.

#### Update `InlineNotification` usage

- The `title`, `subtitle` props have been removed. Compose notification contents
using `children` instead.
- The `actions` prop has been removed. An `InlineNotification` containing an
action or interactive children should be replaced with
`ActionableNotification` configured with the `inline` prop.
- `children` can no longer contain interactive elements.
- The `notificationType` prop is no longer needed and can be removed.
- The default `role` is now `status`. `log` and `alert` can also be used.
- The `closeOnEscape` prop toggles the closing of notifications via the `escape`
key.

#### When using `ActionableNotification`:

- The `inline` prop enables a styling variation resulting in a similar visual
design to `InlineNotification`.
- The `actionButtonLabel` prop configures the action button text.
- The `hasFocus` prop toggles the automatic placement of focus.
- The `closeOnEscape` prop toggles the closing of notifications via the `escape`
key.

### Resources

<Row className="resource-card-group">
<Column colLg={4} colMd={4} noGutterSm>
<ResourceCard
subTitle="Notification usage examples"
href="https://carbon-react-next.netlify.app/?path=/story/components-notifications--toast">
<MdxIcon name="storybook" />
</ResourceCard>
</Column>
<Column colLg={4} colMd={4} noGutterSm>
<ResourceCard
subTitle="Notification accessibility page"
href="https://v11.carbondesignsystem.com/components/notification/accessibility">
<MdxIcon name="bee" />
</ResourceCard>
</Column>
</Row>