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

@@ -1913,7 +1913,7 @@ None.
 ### Props
 
 | Prop name              | Required | Kind             | Reactive | Type                                                                                                           | Default value                     | Description                                                             |
-| :-------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
+| :--------------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------- |
 | kind                   | No       | <code>let</code> | No       | <code>"error" &#124; "info" &#124; "info-square" &#124; "success" &#124; "warning" &#124; "warning-alt"</code> | <code>"error"</code>              | Specify the kind of notification                                        |
 | lowContrast            | No       | <code>let</code> | No       | <code>boolean</code>                                                                                           | <code>false</code>                | Set to `true` to use the low contrast variant                           |
 | timeout                | No       | <code>let</code> | No       | <code>number</code>                                                                                            | <code>0</code>                    | Set the timeout duration (ms) to hide the notification after opening it |
@@ -1921,7 +1921,8 @@ None.
 | title                  | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>""</code>                   | Specify the title text                                                  |
 | subtitle               | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>""</code>                   | Specify the subtitle text                                               |
 | hideCloseButton        | No       | <code>let</code> | No       | <code>boolean</code>                                                                                           | <code>false</code>                | Set to `true` to hide the close button                                  |
-| iconDescription | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>"Closes notification"</code> | Specify the ARIA label for the icon                                     |
+| statusIconDescription  | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>kind + " icon"</code>       | Specify the ARIA label for the status icon                              |
+| closeButtonDescription | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>"Close notification"</code> | Specify the ARIA label for the close button                             |
 
 ### Slots
 
@@ -2449,10 +2450,10 @@ None.
 ### Props
 
 | Prop name        | Required | Kind             | Reactive | Type                                                                                                           | Default value          | Description                           |
-| :--------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------- |
+| :--------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------- |
 | kind             | No       | <code>let</code> | No       | <code>"error" &#124; "info" &#124; "info-square" &#124; "success" &#124; "warning" &#124; "warning-alt"</code> | <code>"error"</code>   | Specify the kind of notification icon |
 | notificationType | No       | <code>let</code> | No       | <code>"toast" &#124; "inline"</code>                                                                           | <code>"toast"</code>   | Set the type of notification          |
-| iconDescription  | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>"Closes notification"</code> | Specify the ARIA label for the icon   |
+| iconDescription  | Yes      | <code>let</code> | No       | --                                                                                                             | <code>undefined</code> | Specify the ARIA label for the icon   |
 
 ### Slots
 
@@ -4311,7 +4312,7 @@ export type CarbonTheme = "white" | "g10" | "g80" | "g90" | "g100";
 ### Props
 
 | Prop name              | Required | Kind             | Reactive | Type                                                                                                           | Default value                     | Description                                                                               |
-| :-------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
+| :--------------------- | :------- | :--------------- | :------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- |
 | kind                   | No       | <code>let</code> | No       | <code>"error" &#124; "info" &#124; "info-square" &#124; "success" &#124; "warning" &#124; "warning-alt"</code> | <code>"error"</code>              | Specify the kind of notification                                                          |
 | lowContrast            | No       | <code>let</code> | No       | <code>boolean</code>                                                                                           | <code>false</code>                | Set to `true` to use the low contrast variant                                             |
 | timeout                | No       | <code>let</code> | No       | <code>number</code>                                                                                            | <code>0</code>                    | Set the timeout duration (ms) to hide the notification after opening it                   |
@@ -4319,7 +4320,8 @@ export type CarbonTheme = "white" | "g10" | "g80" | "g90" | "g100";
 | title                  | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>""</code>                   | Specify the title text                                                                    |
 | subtitle               | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>""</code>                   | Specify the subtitle text                                                                 |
 | caption                | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>""</code>                   | Specify the caption text                                                                  |
-| iconDescription | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>"Closes notification"</code> | Specify the ARIA label for the icon                                                       |
+| statusIconDescription  | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>kind + " icon"</code>       | Specify the ARIA label for the status icon                                                |
+| closeButtonDescription | No       | <code>let</code> | No       | <code>string</code>                                                                                            | <code>"Close notification"</code> | Specify the ARIA label for the close button                                               |
 | hideCloseButton        | No       | <code>let</code> | No       | <code>boolean</code>                                                                                           | <code>false</code>                | Set to `true` to hide the close button                                                    |
 | fullWidth              | No       | <code>let</code> | No       | <code>boolean</code>                                                                                           | <code>false</code>                | Set to `true` for the notification to span<br />the full width of its containing element. |
 

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,

docs/src/pages/components/InlineNotification.svx

@@ -7,6 +7,12 @@ components: ["InlineNotification", "NotificationActionButton"]
   import Preview from "../../components/Preview.svelte";
 </script>
 
+Notification that appears inline.
+
+See [detailed
+usage](https://carbondesignsystem.com/components/notification/usage).  
+See also: [ToastNotification](ToastNotification)
+
 ## Default (error)
 
 <InlineNotification title="Error:" subtitle="An internal server error occurred." />
@@ -27,6 +33,19 @@ components: ["InlineNotification", "NotificationActionButton"]
   <strong slot="subtitle">An internal server error occurred.</strong>
 </InlineNotification>
 
+## 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`.
+
+<InlineNotification 
+  title="错误"
+  subtitle="发生内部服务器错误"
+  statusIconDescription="错误图标"
+  closeButtonDescription="关闭通知"
+/>
+
 ## Hidden close button
 
 <InlineNotification hideCloseButton kind="warning" title="Scheduled maintenance:" subtitle="Maintenance will last 2-4 hours." />

docs/src/pages/components/ToastNotification.svx

@@ -3,6 +3,13 @@
   import Preview from "../../components/Preview.svelte";
 </script>
 
+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)
 
 <ToastNotification title="Error" subtitle="An internal server error occurred." caption="{new Date().toLocaleString()}" />
@@ -30,6 +37,19 @@ Set `fullWidth` to `true` for the notification to span the full width of its con
   <strong slot="caption">{new Date().toLocaleString()}</strong>
 </ToastNotification>
 
+## 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`.
+
+<ToastNotification 
+  title="错误"
+  subtitle="发生内部服务器错误"
+  statusIconDescription="错误图标"
+  closeButtonDescription="关闭通知"
+/>
+
 ## Hidden close button
 
 <ToastNotification hideCloseButton kind="warning" title="Scheduled maintenance" subtitle="Maintenance will last 2-4 hours." caption="{new Date().toLocaleString()}" />

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
   >
     <div class:bx--inline-notification__details="{true}">
-      <NotificationIcon notificationType="inline" kind="{kind}" />
+      <NotificationIcon
+        notificationType="inline"
+        kind="{kind}"
+        iconDescription="{statusIconDescription}"
+      />
       <div class:bx--inline-notification__text-wrapper="{true}">
         <p class:bx--inline-notification__title="{true}">
           <slot name="title">{title}</slot>
@@ -96,7 +106,7 @@
     <slot name="actions" />
     {#if !hideCloseButton}
       <NotificationButton
-        iconDescription="{iconDescription}"
+        iconDescription="{closeButtonDescription}"
         notificationType="inline"
         on:click="{close}"
       />

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";

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
   >
-    <NotificationIcon kind="{kind}" />
+    <NotificationIcon kind="{kind}" iconDescription="{statusIconDescription}" />
     <div class:bx--toast-notification__details="{true}">
       <h3 class:bx--toast-notification__title="{true}">
         <slot name="title">{title}</slot>
@@ -105,7 +111,7 @@
     </div>
     {#if !hideCloseButton}
       <NotificationButton
-        iconDescription="{iconDescription}"
+        iconDescription="{closeButtonDescription}"
         on:click="{close}"
       />
     {/if}

types/Notification/InlineNotification.svelte.d.ts

@@ -52,10 +52,16 @@ export interface InlineNotificationProps
   hideCloseButton?: boolean;
 
   /**
-   * Specify the ARIA label for the icon
+   * Specify the ARIA label for the status icon
-   * @default "Closes notification"
+   * @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<

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<

types/Notification/ToastNotification.svelte.d.ts

@@ -52,10 +52,16 @@ export interface ToastNotificationProps
   caption?: string;
 
   /**
-   * Specify the ARIA label for the icon
+   * Specify the ARIA label for the status icon
-   * @default "Closes notification"
+   * @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