From 81eac8caa4d2c5ff3e88b3bfd29df07560e651bb Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Fri, 22 Oct 2021 16:26:34 -0500 Subject: [PATCH 1/3] docs(migration): add Notification migration docs, update a11y info --- .../components/notification/accessibility.mdx | 15 ++-- src/pages/migrating/guide/develop.mdx | 78 ++++++++++++++++++- 2 files changed, 87 insertions(+), 6 deletions(-) diff --git a/src/pages/components/notification/accessibility.mdx b/src/pages/components/notification/accessibility.mdx index 9c069227edb..a599d2b9371 100644 --- a/src/pages/components/notification/accessibility.mdx +++ b/src/pages/components/notification/accessibility.mdx @@ -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 `
  • ` 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 diff --git a/src/pages/migrating/guide/develop.mdx b/src/pages/migrating/guide/develop.mdx index b950b067145..472b1277c7c 100644 --- a/src/pages/migrating/guide/develop.mdx +++ b/src/pages/migrating/guide/develop.mdx @@ -41,7 +41,7 @@ possible by detailing all of the updates below. | Icons `size` prop | Breaking | [Icons size prop](#icon-size-prop) | `@carbon/react/icons` `@carbon/icons-react` All icons | | Component `className` prop | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | | Event handlers | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | -| Notification | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | +| Notifications | Breaking | [Notifications](#Notifications) | `@carbon/react` | | Tooltip | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | | ContentSwitcher | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | | Layer Component | Breaking | [Layering](#layer-component-breaking) | Components using `light` prop | @@ -664,3 +664,79 @@ Learn more about our Popover component and it's API below: + +## Notifications Breaking + +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 recieve 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 + + + + + + + + + + + + + From 64460430cf33c9cb8e698ee3c8df9ea71d97f56b Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Mon, 25 Oct 2021 14:50:30 -0500 Subject: [PATCH 2/3] Update src/pages/migrating/guide/develop.mdx Co-authored-by: Josefina Mancilla <32556167+jnm2377@users.noreply.github.com> --- src/pages/migrating/guide/develop.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/migrating/guide/develop.mdx b/src/pages/migrating/guide/develop.mdx index 472b1277c7c..5a9325c5414 100644 --- a/src/pages/migrating/guide/develop.mdx +++ b/src/pages/migrating/guide/develop.mdx @@ -670,7 +670,7 @@ Learn more about our Popover component and it's API below: 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 recieve focus and should be used for information-only use cases. These +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 From 5feae47def6f40516e95d663d8fe498885757854 Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Mon, 25 Oct 2021 14:50:36 -0500 Subject: [PATCH 3/3] Update src/pages/migrating/guide/develop.mdx Co-authored-by: Josefina Mancilla <32556167+jnm2377@users.noreply.github.com> --- src/pages/migrating/guide/develop.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/migrating/guide/develop.mdx b/src/pages/migrating/guide/develop.mdx index 5a9325c5414..8540581864d 100644 --- a/src/pages/migrating/guide/develop.mdx +++ b/src/pages/migrating/guide/develop.mdx @@ -41,7 +41,7 @@ possible by detailing all of the updates below. | Icons `size` prop | Breaking | [Icons size prop](#icon-size-prop) | `@carbon/react/icons` `@carbon/icons-react` All icons | | Component `className` prop | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | | Event handlers | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | -| Notifications | Breaking | [Notifications](#Notifications) | `@carbon/react` | +| Notifications | Breaking | [Notifications](#notifications-breaking) | `@carbon/react` | | Tooltip | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | | ContentSwitcher | Breaking | [CSS Grid](#css-grid-breaking) | `@carbon/react` | | Layer Component | Breaking | [Layering](#layer-component-breaking) | Components using `light` prop |