[terra-alert] Add ID prop (#4048)

packages/terra-alert/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+* Added
+  * Added `id` prop.
+
 ## 4.90.0 - (February 27, 2024)
 
 * Changed

packages/terra-alert/src/Alert.jsx

@@ -63,6 +63,12 @@ const propTypes = {
    * Callback function triggered when Dismiss button is clicked. The presence of this prop will cause the Dismiss button to be included on the notification banner.
    */
   onDismiss: PropTypes.func,
+  /**
+   * The unique ID of the alert that is used to identify the alert title and message content.
+   * These IDs can be used to associate action elements with the alert via aria-describedby, in the format
+   * `alert-title-${id}`.
+   * */
+  id: PropTypes.string,
   /**
    * @private
    * intl object programmatically imported through injectIntl from react-intl.
@@ -136,6 +142,7 @@ const Alert = ({
   disableAlertActionFocus,
   onDismiss,
   intl,
+  id,
   role,
   title,
   type,
@@ -169,7 +176,7 @@ const Alert = ({
   const focusContainerClassName = cx('focus-container');
   const contentContainerClassName = cx('content-container');
 
-  const alertId = uuidv4();
+  const alertId = id || uuidv4();
   const alertTitleId = `alert-title-${alertId}`;
   const alertMessageId = `alert-message-${alertId}`;
 
@@ -234,6 +241,7 @@ const Alert = ({
     >
       <div
         role={role || defaultRole}
+        id={id}
         {...customProps}
         className={alertClassNames}
       >

packages/terra-alert/tests/jest/Alert.test.jsx

@@ -79,6 +79,13 @@ describe('Alert with props', () => {
     expect(alertTitle.text()).toEqual('<VisuallyHiddenText />Custom Title');
     expect(wrapper).toMatchSnapshot();
   });
+
+  it('should render an alert with provided id', () => {
+    const wrapper = enzymeIntl.shallowWithIntl(<Alert id="alert-id" />).dive();
+
+    expect(wrapper.find('.title').prop('id')).toEqual('alert-title-alert-id');
+    expect(wrapper.find('.section').prop('id')).toEqual('alert-message-alert-id');
+  });
 });
 
 describe('Dismissible Alert that includes actions section', () => {

packages/terra-core-docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+* Added
+  * Added documentation on using new `id` prop with action elements in `terra-alert`.
+
 ## 1.61.0 - (February 28, 2024)
 
 * Updated

packages/terra-core-docs/src/terra-dev-site/doc/alert/AccessibilityGuide.2.doc.mdx

@@ -4,6 +4,7 @@ import Whitespace from '../../common/layout-helpers/Whitespace';
 import AlertActionFocusDemo from './example/AlertActionFocusDemo';
 import CustomExample from './example/CustomExample?dev-site-example';
 import CustomExampleNoTitle from './example/CustomExampleNoTitle?dev-site-example';
+import ActionExample from './example/ActionExample?dev-site-example';
 
 import Hyperlink from 'terra-hyperlink';
 
@@ -116,5 +117,18 @@ In combination with the notification criticality, screen reader users should und
 <CustomExampleNoTitle title="Bad: Avoid notifications with no titles" />
 <CustomExample title="Good: Titles help users understand notifications" />
 
+#### Actions
+
+- Interactable elements belonging to notification banners (such as dismiss buttons and action elements) must be associated with the banner.
+  This is handled by default for dismiss buttons, but not consumer-defined action elements.
+- Terra provides an optional `id` prop to facilitate associating action elements to the notification banner. Action elements should set
+  `aria-describedby` to the title of the notification banner.
+  - `alert-title-${id}` - The ID of the title of the notification banner (e.g. "Alert", "Error", "Warning", custom titles, etc.)
+
+<ActionExample
+  title="Notification Banner with Action"
+  description="This example uses the id prop and aria-describedby to associate an action element with the notification banner."
+/>
+
 ## Linked References:
 1. ["Accessible Rich Internet Applications (WAI-ARIA) 1.3"](https://w3c.github.io/aria/). World Wide Web Consortium. Last updated 01 May 2023. Retrieved 2 May 2023.

packages/terra-core-docs/src/terra-dev-site/doc/alert/example/ActionExample.jsx

@@ -19,6 +19,7 @@ const AlertActionButton = () => {
       customIcon={<IconHazardLow />}
       action={(
         <Button
+          aria-describedby="alert-title-actionAlert"
           text="Action"
           variant="emphasis"
           onClick={action}