From 50066966dae8528142d3c6968f421fee5e1fb512 Mon Sep 17 00:00:00 2001 From: Enrico Sacchetti Date: Sun, 18 Dec 2022 18:28:23 -0500 Subject: [PATCH] feat(notification)!: replace `iconDescription` prop with `statusIconDescription`, `closeButtonDescription` (#1591) Fixes #672, fixes #1563 * breaking: remove `iconDescription` prop from `InlineNotification`, `ToastNotification` * breaking: require `iconDescription` prop in `NotificationIcon` * feat: add new `statusIconDescription` and `closeButtonDescription` to `InlineNotification`, `ToastNotification` --- COMPONENT_INDEX.md | 56 ++++++++++--------- docs/src/COMPONENT_API.json | 40 ++++++++++--- .../pages/components/InlineNotification.svx | 19 +++++++ .../pages/components/ToastNotification.svx | 20 +++++++ src/Notification/InlineNotification.svelte | 18 ++++-- src/Notification/NotificationIcon.svelte | 2 +- src/Notification/ToastNotification.svelte | 14 +++-- .../InlineNotification.svelte.d.ts | 12 +++- .../Notification/NotificationIcon.svelte.d.ts | 4 +- .../ToastNotification.svelte.d.ts | 12 +++- 10 files changed, 144 insertions(+), 53 deletions(-) diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md index 72d9321a..30e93290 100644 --- a/COMPONENT_INDEX.md +++ b/COMPONENT_INDEX.md @@ -1912,16 +1912,17 @@ None. ### Props -| Prop name | Required | Kind | Reactive | Type | Default value | Description | -| :-------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------- | -| kind | No | let | No | "error" | "info" | "info-square" | "success" | "warning" | "warning-alt" | "error" | Specify the kind of notification | -| lowContrast | No | let | No | boolean | false | Set to `true` to use the low contrast variant | -| timeout | No | let | No | number | 0 | Set the timeout duration (ms) to hide the notification after opening it | -| role | No | let | No | string | "alert" | Set the `role` attribute | -| title | No | let | No | string | "" | Specify the title text | -| subtitle | No | let | No | string | "" | Specify the subtitle text | -| hideCloseButton | No | let | No | boolean | false | Set to `true` to hide the close button | -| iconDescription | No | let | No | string | "Closes notification" | Specify the ARIA label for the icon | +| Prop name | Required | Kind | Reactive | Type | Default value | Description | +| :--------------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------- | +| kind | No | let | No | "error" | "info" | "info-square" | "success" | "warning" | "warning-alt" | "error" | Specify the kind of notification | +| lowContrast | No | let | No | boolean | false | Set to `true` to use the low contrast variant | +| timeout | No | let | No | number | 0 | Set the timeout duration (ms) to hide the notification after opening it | +| role | No | let | No | string | "alert" | Set the `role` attribute | +| title | No | let | No | string | "" | Specify the title text | +| subtitle | No | let | No | string | "" | Specify the subtitle text | +| hideCloseButton | No | let | No | boolean | false | Set to `true` to hide the close button | +| statusIconDescription | No | let | No | string | kind + " icon" | Specify the ARIA label for the status icon | +| closeButtonDescription | No | let | No | string | "Close notification" | Specify the ARIA label for the close button | ### Slots @@ -2448,11 +2449,11 @@ None. ### Props -| Prop name | Required | Kind | Reactive | Type | Default value | Description | -| :--------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------- | -| kind | No | let | No | "error" | "info" | "info-square" | "success" | "warning" | "warning-alt" | "error" | Specify the kind of notification icon | -| notificationType | No | let | No | "toast" | "inline" | "toast" | Set the type of notification | -| iconDescription | No | let | No | string | "Closes notification" | Specify the ARIA label for the icon | +| Prop name | Required | Kind | Reactive | Type | Default value | Description | +| :--------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------- | +| kind | No | let | No | "error" | "info" | "info-square" | "success" | "warning" | "warning-alt" | "error" | Specify the kind of notification icon | +| notificationType | No | let | No | "toast" | "inline" | "toast" | Set the type of notification | +| iconDescription | Yes | let | No | -- | undefined | Specify the ARIA label for the icon | ### Slots @@ -4310,18 +4311,19 @@ export type CarbonTheme = "white" | "g10" | "g80" | "g90" | "g100"; ### Props -| Prop name | Required | Kind | Reactive | Type | Default value | Description | -| :-------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------- | -| kind | No | let | No | "error" | "info" | "info-square" | "success" | "warning" | "warning-alt" | "error" | Specify the kind of notification | -| lowContrast | No | let | No | boolean | false | Set to `true` to use the low contrast variant | -| timeout | No | let | No | number | 0 | Set the timeout duration (ms) to hide the notification after opening it | -| role | No | let | No | string | "alert" | Set the `role` attribute | -| title | No | let | No | string | "" | Specify the title text | -| subtitle | No | let | No | string | "" | Specify the subtitle text | -| caption | No | let | No | string | "" | Specify the caption text | -| iconDescription | No | let | No | string | "Closes notification" | Specify the ARIA label for the icon | -| hideCloseButton | No | let | No | boolean | false | Set to `true` to hide the close button | -| fullWidth | No | let | No | boolean | false | Set to `true` for the notification to span
the full width of its containing element. | +| Prop name | Required | Kind | Reactive | Type | Default value | Description | +| :--------------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- | +| kind | No | let | No | "error" | "info" | "info-square" | "success" | "warning" | "warning-alt" | "error" | Specify the kind of notification | +| lowContrast | No | let | No | boolean | false | Set to `true` to use the low contrast variant | +| timeout | No | let | No | number | 0 | Set the timeout duration (ms) to hide the notification after opening it | +| role | No | let | No | string | "alert" | Set the `role` attribute | +| title | No | let | No | string | "" | Specify the title text | +| subtitle | No | let | No | string | "" | Specify the subtitle text | +| caption | No | let | No | string | "" | Specify the caption text | +| statusIconDescription | No | let | No | string | kind + " icon" | Specify the ARIA label for the status icon | +| closeButtonDescription | No | let | No | string | "Close notification" | Specify the ARIA label for the close button | +| hideCloseButton | No | let | No | boolean | false | Set to `true` to hide the close button | +| fullWidth | No | let | No | boolean | false | Set to `true` for the notification to span
the full width of its containing element. | ### Slots diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json index 88965aab..ce55e9ba 100644 --- a/docs/src/COMPONENT_API.json +++ b/docs/src/COMPONENT_API.json @@ -5627,11 +5627,23 @@ "reactive": false }, { - "name": "iconDescription", + "name": "statusIconDescription", "kind": "let", - "description": "Specify the ARIA label for the icon", + "description": "Specify the ARIA label for the status icon", "type": "string", - "value": "\"Closes notification\"", + "value": "kind + \" icon\"", + "isFunction": false, + "isFunctionDeclaration": false, + "isRequired": false, + "constant": false, + "reactive": false + }, + { + "name": "closeButtonDescription", + "kind": "let", + "description": "Specify the ARIA label for the close button", + "type": "string", + "value": "\"Close notification\"", "isFunction": false, "isFunctionDeclaration": false, "isRequired": false, @@ -7486,11 +7498,9 @@ "name": "iconDescription", "kind": "let", "description": "Specify the ARIA label for the icon", - "type": "string", - "value": "\"Closes notification\"", "isFunction": false, "isFunctionDeclaration": false, - "isRequired": false, + "isRequired": true, "constant": false, "reactive": false } @@ -13391,11 +13401,23 @@ "reactive": false }, { - "name": "iconDescription", + "name": "statusIconDescription", "kind": "let", - "description": "Specify the ARIA label for the icon", + "description": "Specify the ARIA label for the status icon", "type": "string", - "value": "\"Closes notification\"", + "value": "kind + \" icon\"", + "isFunction": false, + "isFunctionDeclaration": false, + "isRequired": false, + "constant": false, + "reactive": false + }, + { + "name": "closeButtonDescription", + "kind": "let", + "description": "Specify the ARIA label for the close button", + "type": "string", + "value": "\"Close notification\"", "isFunction": false, "isFunctionDeclaration": false, "isRequired": false, diff --git a/docs/src/pages/components/InlineNotification.svx b/docs/src/pages/components/InlineNotification.svx index 1652fac1..33482ced 100644 --- a/docs/src/pages/components/InlineNotification.svx +++ b/docs/src/pages/components/InlineNotification.svx @@ -7,6 +7,12 @@ components: ["InlineNotification", "NotificationActionButton"] import Preview from "../../components/Preview.svelte"; +Notification that appears inline. + +See [detailed +usage](https://carbondesignsystem.com/components/notification/usage). +See also: [ToastNotification](ToastNotification) + ## Default (error) @@ -27,6 +33,19 @@ components: ["InlineNotification", "NotificationActionButton"] An internal server error occurred. +## Accessible icon descriptions + +The status icon and close button icon descriptions appear on cursor hover and are read +by assistive technology. Default descriptions are provided in English and can be +overridden via `statusIconDescription` and `closeButtonDescription`. + + + ## Hidden close button diff --git a/docs/src/pages/components/ToastNotification.svx b/docs/src/pages/components/ToastNotification.svx index 63a8f03c..571b6289 100644 --- a/docs/src/pages/components/ToastNotification.svx +++ b/docs/src/pages/components/ToastNotification.svx @@ -3,6 +3,13 @@ import Preview from "../../components/Preview.svelte"; +Toasts are non-modal, time-based window elements used to display short messages; +they usually appear at the top of the screen and disappear after a few seconds. + +See [detailed +usage](https://carbondesignsystem.com/components/notification/usage). +See also: [InlineNotification](InlineNotification) + ## Default (error) @@ -30,6 +37,19 @@ Set `fullWidth` to `true` for the notification to span the full width of its con {new Date().toLocaleString()} +## Accessible icon descriptions + +The status icon and close button icon descriptions appear on cursor hover and are read +by assistive technology. Default descriptions are provided in English and can be +overridden via `statusIconDescription` and `closeButtonDescription`. + + + ## Hidden close button diff --git a/src/Notification/InlineNotification.svelte b/src/Notification/InlineNotification.svelte index 4cd57717..5bde027e 100644 --- a/src/Notification/InlineNotification.svelte +++ b/src/Notification/InlineNotification.svelte @@ -27,8 +27,14 @@ /** Set to `true` to hide the close button */ export let hideCloseButton = false; - /** Specify the ARIA label for the icon */ - export let iconDescription = "Closes notification"; + /** + * Specify the ARIA label for the status icon + * @type {string} + * */ + export let statusIconDescription = kind + " icon"; + + /** Specify the ARIA label for the close button */ + export let closeButtonDescription = "Close notification"; import { createEventDispatcher, onMount } from "svelte"; import NotificationIcon from "./NotificationIcon.svelte"; @@ -82,7 +88,11 @@ on:mouseleave >
- +

{title} @@ -96,7 +106,7 @@ {#if !hideCloseButton} diff --git a/src/Notification/NotificationIcon.svelte b/src/Notification/NotificationIcon.svelte index dc6defa8..f106c4b5 100644 --- a/src/Notification/NotificationIcon.svelte +++ b/src/Notification/NotificationIcon.svelte @@ -12,7 +12,7 @@ export let notificationType = "toast"; /** Specify the ARIA label for the icon */ - export let iconDescription = "Closes notification"; + export let iconDescription; import CheckmarkFilled from "../icons/CheckmarkFilled.svelte"; import ErrorFilled from "../icons/ErrorFilled.svelte"; diff --git a/src/Notification/ToastNotification.svelte b/src/Notification/ToastNotification.svelte index 0048fd47..cdc72ea6 100644 --- a/src/Notification/ToastNotification.svelte +++ b/src/Notification/ToastNotification.svelte @@ -27,8 +27,14 @@ /** Specify the caption text */ export let caption = ""; - /** Specify the ARIA label for the icon */ - export let iconDescription = "Closes notification"; + /** + * Specify the ARIA label for the status icon + * @type {string} + * */ + export let statusIconDescription = kind + " icon"; + + /** Specify the ARIA label for the close button */ + export let closeButtonDescription = "Close notification"; /** Set to `true` to hide the close button */ export let hideCloseButton = false; @@ -90,7 +96,7 @@ on:mouseenter on:mouseleave > - +

{title} @@ -105,7 +111,7 @@

{#if !hideCloseButton} {/if} diff --git a/types/Notification/InlineNotification.svelte.d.ts b/types/Notification/InlineNotification.svelte.d.ts index 882dab94..454455de 100644 --- a/types/Notification/InlineNotification.svelte.d.ts +++ b/types/Notification/InlineNotification.svelte.d.ts @@ -52,10 +52,16 @@ export interface InlineNotificationProps hideCloseButton?: boolean; /** - * Specify the ARIA label for the icon - * @default "Closes notification" + * Specify the ARIA label for the status icon + * @default kind + " icon" */ - iconDescription?: string; + statusIconDescription?: string; + + /** + * Specify the ARIA label for the close button + * @default "Close notification" + */ + closeButtonDescription?: string; } export default class InlineNotification extends SvelteComponentTyped< diff --git a/types/Notification/NotificationIcon.svelte.d.ts b/types/Notification/NotificationIcon.svelte.d.ts index c75da8b9..9e69e5b9 100644 --- a/types/Notification/NotificationIcon.svelte.d.ts +++ b/types/Notification/NotificationIcon.svelte.d.ts @@ -22,9 +22,9 @@ export interface NotificationIconProps { /** * Specify the ARIA label for the icon - * @default "Closes notification" + * @default undefined */ - iconDescription?: string; + iconDescription: undefined; } export default class NotificationIcon extends SvelteComponentTyped< diff --git a/types/Notification/ToastNotification.svelte.d.ts b/types/Notification/ToastNotification.svelte.d.ts index 9e86f6ed..4bc6d359 100644 --- a/types/Notification/ToastNotification.svelte.d.ts +++ b/types/Notification/ToastNotification.svelte.d.ts @@ -52,10 +52,16 @@ export interface ToastNotificationProps caption?: string; /** - * Specify the ARIA label for the icon - * @default "Closes notification" + * Specify the ARIA label for the status icon + * @default kind + " icon" */ - iconDescription?: string; + statusIconDescription?: string; + + /** + * Specify the ARIA label for the close button + * @default "Close notification" + */ + closeButtonDescription?: string; /** * Set to `true` to hide the close button