@momentum-design/components 0.131.4 → 0.131.6

package/dist/components/input/input.component.d.ts

@@ -214,5 +214,13 @@ declare class Input extends Input_base implements AssociatedFormControl {
     protected renderInputElement(type: InputType, hidePlaceholder?: boolean): import("lit-html").TemplateResult<1>;
     render(): import("lit-html").TemplateResult<1>;
     static styles: Array<CSSResult>;
+    static shadowRootOptions: {
+        delegatesFocus: boolean;
+        clonable?: boolean;
+        customElementRegistry?: CustomElementRegistry;
+        mode: ShadowRootMode;
+        serializable?: boolean;
+        slotAssignment?: SlotAssignmentMode;
+    };
 }
 export default Input;

package/dist/components/input/input.component.js

@@ -351,6 +351,7 @@ class Input extends KeyToActionMixin(AutoFocusOnMountMixin(FormInternalsMixin(Da
     }
 }
 Input.styles = [...FormfieldWrapper.styles, ...styles];
+Input.shadowRootOptions = { ...FormfieldWrapper.shadowRootOptions, delegatesFocus: true };
 __decorate([
     property({ type: String }),
     __metadata("design:type", Object)

package/dist/components/screenreaderannouncer/screenreaderannouncer.component.d.ts

@@ -6,6 +6,9 @@ import { AriaLive } from './screenreaderannouncer.types';
  *
  * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.
  *
+ * Consumers can also use the public `announce` function to trigger announcements programmatically
+ * by passing an options object where `announcement` is required and all other fields are optional.
+ *
  * **Internal logic**
  *
  * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not
@@ -13,9 +16,25 @@ import { AriaLive } from './screenreaderannouncer.types';
  * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element
  * is created in the DOM.
  *
+ * If you provide a custom `identity`, you must ensure that the element exists and is visually hidden.
+ *
+ * Example CSS:
+ *
+ * ```css
+ * #your-custom-announcer-id {
+ *   clip: rect(0 0 0 0);
+ *   clip-path: inset(50%);
+ *   height: 1px;
+ *   overflow: hidden;
+ *   position: absolute;
+ *   white-space: nowrap;
+ *   width: 1px;
+ * }
+ * ```
+ *
  * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with
  * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.
- * After delay of `delay` milliseconds, a <p> element with the announcement text is appended to the `<div>` element.
+ * After delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.
  *
  * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.
  *
@@ -25,6 +44,10 @@ import { AriaLive } from './screenreaderannouncer.types';
  * **Note**
  * 1. The default delay of 150 miliseconds is used as we dynamically generate the
  * aria-live region in the DOM and add the announcement text to it.
+ * 2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`
+ * for that identity is effectively determined by the first instance that creates announcements for it.
+ * Changing `data-aria-live` in later instances for the same identity will not update already-created
+ * live-region containers.
  * 3. If no `identity` is provided, all the screen reader components will create and use only one
  * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.
  *
@@ -50,6 +73,10 @@ declare class ScreenreaderAnnouncer extends Component {
     /**
      * Aria live value for announcement.
      *
+     * For a shared `identity`, this value should be treated as immutable after initial usage.
+     * The first `mdc-screenreaderannouncer` instance that creates announcements for that
+     * identity determines the `aria-live` value for the created live-region containers.
+     *
      * @default 'polite'
      */
     dataAriaLive: AriaLive;
@@ -93,12 +120,18 @@ declare class ScreenreaderAnnouncer extends Component {
      * The div element is appended to the element in the DOM identified with id as
      * identity attribute.
      *
-     * @param announcement - The announcement to be made.
-     * @param delay - The delay in milliseconds before announcing the message.
-     * @param timeout - The timeout in milliseconds before removing the announcement.
-     * @param ariaLive - The aria live value for the announcement.
+     * @param options - Announcement configuration object with the following fields:
+     *   - `announcement` (required): The announcement to be made.
+     *   - `delay` (optional): The delay in milliseconds before announcing the message.
+     *   - `timeout` (optional): The timeout in milliseconds before removing the announcement.
+     *   - `ariaLive` (optional): The aria live value for the announcement.
      */
-    announce(announcement: string, delay: number, timeout: number, ariaLive: AriaLive): void;
+    announce({ announcement, delay, timeout, ariaLive, }: {
+        announcement: string;
+        delay?: number;
+        timeout?: number;
+        ariaLive?: AriaLive;
+    }): void;
     /**
      * Clears all timeouts and removes all announcements from the screen reader.
      */

package/dist/components/screenreaderannouncer/screenreaderannouncer.component.js

@@ -18,6 +18,9 @@ import styles from './screenreaderannouncer.styles';
  *
  * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.
  *
+ * Consumers can also use the public `announce` function to trigger announcements programmatically
+ * by passing an options object where `announcement` is required and all other fields are optional.
+ *
  * **Internal logic**
  *
  * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not
@@ -25,9 +28,25 @@ import styles from './screenreaderannouncer.styles';
  * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element
  * is created in the DOM.
  *
+ * If you provide a custom `identity`, you must ensure that the element exists and is visually hidden.
+ *
+ * Example CSS:
+ *
+ * ```css
+ * #your-custom-announcer-id {
+ *   clip: rect(0 0 0 0);
+ *   clip-path: inset(50%);
+ *   height: 1px;
+ *   overflow: hidden;
+ *   position: absolute;
+ *   white-space: nowrap;
+ *   width: 1px;
+ * }
+ * ```
+ *
  * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with
  * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.
- * After delay of `delay` milliseconds, a <p> element with the announcement text is appended to the `<div>` element.
+ * After delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.
  *
  * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.
  *
@@ -37,6 +56,10 @@ import styles from './screenreaderannouncer.styles';
  * **Note**
  * 1. The default delay of 150 miliseconds is used as we dynamically generate the
  * aria-live region in the DOM and add the announcement text to it.
+ * 2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`
+ * for that identity is effectively determined by the first instance that creates announcements for it.
+ * Changing `data-aria-live` in later instances for the same identity will not update already-created
+ * live-region containers.
  * 3. If no `identity` is provided, all the screen reader components will create and use only one
  * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.
  *
@@ -64,6 +87,10 @@ class ScreenreaderAnnouncer extends Component {
         /**
          * Aria live value for announcement.
          *
+         * For a shared `identity`, this value should be treated as immutable after initial usage.
+         * The first `mdc-screenreaderannouncer` instance that creates announcements for that
+         * identity determines the `aria-live` value for the created live-region containers.
+         *
          * @default 'polite'
          */
         this.dataAriaLive = DEFAULTS.ARIA_LIVE;
@@ -106,18 +133,19 @@ class ScreenreaderAnnouncer extends Component {
      * The div element is appended to the element in the DOM identified with id as
      * identity attribute.
      *
-     * @param announcement - The announcement to be made.
-     * @param delay - The delay in milliseconds before announcing the message.
-     * @param timeout - The timeout in milliseconds before removing the announcement.
-     * @param ariaLive - The aria live value for the announcement.
+     * @param options - Announcement configuration object with the following fields:
+     *   - `announcement` (required): The announcement to be made.
+     *   - `delay` (optional): The delay in milliseconds before announcing the message.
+     *   - `timeout` (optional): The timeout in milliseconds before removing the announcement.
+     *   - `ariaLive` (optional): The aria live value for the announcement.
      */
-    announce(announcement, delay, timeout, ariaLive) {
+    announce({ announcement, delay, timeout, ariaLive, }) {
         var _a;
         if (announcement.length > 0) {
             const announcementId = `mdc-screenreaderannouncer-announcement-${uuidv4()}`;
             const announcementContainer = document.createElement('div');
             announcementContainer.setAttribute('id', announcementId);
-            announcementContainer.setAttribute('aria-live', ariaLive);
+            announcementContainer.setAttribute('aria-live', ariaLive !== null && ariaLive !== void 0 ? ariaLive : this.dataAriaLive);
             (_a = this.getElementByIdAcrossShadowRoot(this.identity)) === null || _a === void 0 ? void 0 : _a.appendChild(announcementContainer);
             const timeOutId = window.setTimeout(() => {
                 const announcementElement = document.createElement('p');
@@ -126,9 +154,9 @@ class ScreenreaderAnnouncer extends Component {
                 this.ariaLiveAnnouncementIds.push(announcementId);
                 const timeOutId = window.setTimeout(() => {
                     announcementContainer.remove();
-                }, timeout);
+                }, timeout !== null && timeout !== void 0 ? timeout : this.timeout);
                 this.timeOutIds.push(timeOutId);
-            }, delay);
+            }, delay !== null && delay !== void 0 ? delay : this.delay);
             this.timeOutIds.push(timeOutId);
         }
     }
@@ -224,7 +252,12 @@ class ScreenreaderAnnouncer extends Component {
         // create single debounced function that will read latest this.announcement when executed
         this.debouncedAnnounce = debounce(() => {
             if (this.announcement && this.announcement.length > 0) {
-                this.announce(this.announcement, this.delay, this.timeout, this.dataAriaLive);
+                this.announce({
+                    announcement: this.announcement,
+                    delay: this.delay,
+                    timeout: this.timeout,
+                    ariaLive: this.dataAriaLive,
+                });
                 this.announcement = '';
             }
         }, this.debounceTime);

package/dist/custom-elements.json

@@ -18089,6 +18089,15 @@
                 "module": "utils/mixins/FormInternalsMixin.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "shadowRootOptions",
+              "type": {
+                "text": "object"
+              },
+              "static": true,
+              "default": "{ ...FormfieldWrapper.shadowRootOptions, delegatesFocus: true }"
+            },
             {
               "kind": "field",
               "name": "size",
@@ -30551,6 +30560,19 @@
                 "module": "utils/mixins/FormInternalsMixin.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "shadowRootOptions",
+              "type": {
+                "text": "object"
+              },
+              "static": true,
+              "default": "{ ...FormfieldWrapper.shadowRootOptions, delegatesFocus: true }",
+              "inheritedFrom": {
+                "name": "Input",
+                "module": "components/input/input.component.js"
+              }
+            },
             {
               "kind": "field",
               "name": "showButtonAriaLabel",
@@ -35565,40 +35587,23 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`mdc-screenreaderannouncer` can be used to announce messages with the screen reader.\n\nTo make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.\n\n**Internal logic**\n\nWhen the screenreader announcer is connected to the DOM, if the `identity` attribute is not\nprovided, it is set to `mdc-screenreaderannouncer-identity` and a `<div>` element with this id is created\nin the DOM. If the `identity` attribute is provided, the identity element is used and no new element\nis created in the DOM.\n\nWhen the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with\n`aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.\nAfter delay of `delay` milliseconds, a <p> element with the announcement text is appended to the `<div>` element.\n\nThe announcement `<div>` element is removed from the DOM after `timeout` milliseconds.\n\nWhen the screen announcer component is disconnected from the DOM, all the timeouts are cleared and\nall the announcement elements added are removed from the DOM and timeouts cleared.\n\n**Note**\n1. The default delay of 150 miliseconds is used as we dynamically generate the\naria-live region in the DOM and add the announcement text to it.\n3. If no `identity` is provided, all the screen reader components will create and use only one\n`<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.\n\nReference: https://patrickhlauke.github.io/aria/tests/live-regions/",
+          "description": "`mdc-screenreaderannouncer` can be used to announce messages with the screen reader.\n\nTo make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.\n\nConsumers can also use the public `announce` function to trigger announcements programmatically\nby passing an options object where `announcement` is required and all other fields are optional.\n\n**Internal logic**\n\nWhen the screenreader announcer is connected to the DOM, if the `identity` attribute is not\nprovided, it is set to `mdc-screenreaderannouncer-identity` and a `<div>` element with this id is created\nin the DOM. If the `identity` attribute is provided, the identity element is used and no new element\nis created in the DOM.\n\nIf you provide a custom `identity`, you must ensure that the element exists and is visually hidden.\n\nExample CSS:\n\n```css\n#your-custom-announcer-id {\n  clip: rect(0 0 0 0);\n  clip-path: inset(50%);\n  height: 1px;\n  overflow: hidden;\n  position: absolute;\n  white-space: nowrap;\n  width: 1px;\n}\n```\n\nWhen the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with\n`aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.\nAfter delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.\n\nThe announcement `<div>` element is removed from the DOM after `timeout` milliseconds.\n\nWhen the screen announcer component is disconnected from the DOM, all the timeouts are cleared and\nall the announcement elements added are removed from the DOM and timeouts cleared.\n\n**Note**\n1. The default delay of 150 miliseconds is used as we dynamically generate the\naria-live region in the DOM and add the announcement text to it.\n2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`\nfor that identity is effectively determined by the first instance that creates announcements for it.\nChanging `data-aria-live` in later instances for the same identity will not update already-created\nlive-region containers.\n3. If no `identity` is provided, all the screen reader components will create and use only one\n`<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.\n\nReference: https://patrickhlauke.github.io/aria/tests/live-regions/",
           "name": "ScreenreaderAnnouncer",
           "members": [
             {
               "kind": "method",
               "name": "announce",
+              "privacy": "public",
               "parameters": [
                 {
-                  "name": "announcement",
-                  "type": {
-                    "text": "string"
-                  },
-                  "description": "The announcement to be made."
-                },
-                {
-                  "name": "delay",
-                  "type": {
-                    "text": "number"
-                  },
-                  "description": "The delay in milliseconds before announcing the message."
-                },
-                {
-                  "name": "timeout",
+                  "name": "{\n    announcement,\n    delay,\n    timeout,\n    ariaLive,\n  }",
                   "type": {
-                    "text": "number"
-                  },
-                  "description": "The timeout in milliseconds before removing the announcement."
+                    "text": "{\n    announcement: string;\n    delay?: number;\n    timeout?: number;\n    ariaLive?: AriaLive;\n  }"
+                  }
                 },
                 {
-                  "name": "ariaLive",
-                  "type": {
-                    "text": "AriaLive"
-                  },
-                  "description": "The aria live value for the announcement."
+                  "description": "Announcement configuration object with the following fields:\n- `announcement` (required): The announcement to be made.\n- `delay` (optional): The delay in milliseconds before announcing the message.\n- `timeout` (optional): The timeout in milliseconds before removing the announcement.\n- `ariaLive` (optional): The aria live value for the announcement.",
+                  "name": "options"
                 }
               ],
               "description": "Announces the given announcement to the screen reader.\n\nA div element with aria-live attribute set to the given ariaLive value is created\nand a p element with the announcement text is appended to it.\n\nThe div element is appended to the element in the DOM identified with id as\nidentity attribute."
@@ -35632,7 +35637,7 @@
               "type": {
                 "text": "AriaLive"
               },
-              "description": "Aria live value for announcement.",
+              "description": "Aria live value for announcement.\n\nFor a shared `identity`, this value should be treated as immutable after initial usage.\nThe first `mdc-screenreaderannouncer` instance that creates announcements for that\nidentity determines the `aria-live` value for the created live-region containers.",
               "default": "'polite'",
               "attribute": "data-aria-live",
               "reflects": true
@@ -35712,7 +35717,7 @@
               "type": {
                 "text": "AriaLive"
               },
-              "description": "Aria live value for announcement.",
+              "description": "Aria live value for announcement.\n\nFor a shared `identity`, this value should be treated as immutable after initial usage.\nThe first `mdc-screenreaderannouncer` instance that creates announcements for that\nidentity determines the `aria-live` value for the created live-region containers.",
               "default": "'polite'",
               "fieldName": "dataAriaLive"
             },
@@ -35749,7 +35754,7 @@
             "module": "/src/models"
           },
           "tagName": "mdc-screenreaderannouncer",
-          "jsDoc": "/**\n * `mdc-screenreaderannouncer` can be used to announce messages with the screen reader.\n *\n * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.\n *\n * **Internal logic**\n *\n * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not\n * provided, it is set to `mdc-screenreaderannouncer-identity` and a `<div>` element with this id is created\n * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element\n * is created in the DOM.\n *\n * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with\n * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.\n * After delay of `delay` milliseconds, a <p> element with the announcement text is appended to the `<div>` element.\n *\n * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.\n *\n * When the screen announcer component is disconnected from the DOM, all the timeouts are cleared and\n * all the announcement elements added are removed from the DOM and timeouts cleared.\n *\n * **Note**\n * 1. The default delay of 150 miliseconds is used as we dynamically generate the\n * aria-live region in the DOM and add the announcement text to it.\n * 3. If no `identity` is provided, all the screen reader components will create and use only one\n * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.\n *\n * Reference: https://patrickhlauke.github.io/aria/tests/live-regions/\n *\n * @tagname mdc-screenreaderannouncer\n */",
+          "jsDoc": "/**\n * `mdc-screenreaderannouncer` can be used to announce messages with the screen reader.\n *\n * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.\n *\n * Consumers can also use the public `announce` function to trigger announcements programmatically\n * by passing an options object where `announcement` is required and all other fields are optional.\n *\n * **Internal logic**\n *\n * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not\n * provided, it is set to `mdc-screenreaderannouncer-identity` and a `<div>` element with this id is created\n * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element\n * is created in the DOM.\n *\n * If you provide a custom `identity`, you must ensure that the element exists and is visually hidden.\n *\n * Example CSS:\n *\n * ```css\n * #your-custom-announcer-id {\n *   clip: rect(0 0 0 0);\n *   clip-path: inset(50%);\n *   height: 1px;\n *   overflow: hidden;\n *   position: absolute;\n *   white-space: nowrap;\n *   width: 1px;\n * }\n * ```\n *\n * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with\n * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.\n * After delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.\n *\n * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.\n *\n * When the screen announcer component is disconnected from the DOM, all the timeouts are cleared and\n * all the announcement elements added are removed from the DOM and timeouts cleared.\n *\n * **Note**\n * 1. The default delay of 150 miliseconds is used as we dynamically generate the\n * aria-live region in the DOM and add the announcement text to it.\n * 2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`\n * for that identity is effectively determined by the first instance that creates announcements for it.\n * Changing `data-aria-live` in later instances for the same identity will not update already-created\n * live-region containers.\n * 3. If no `identity` is provided, all the screen reader components will create and use only one\n * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.\n *\n * Reference: https://patrickhlauke.github.io/aria/tests/live-regions/\n *\n * @tagname mdc-screenreaderannouncer\n */",
           "customElement": true
         }
       ],
@@ -36629,6 +36634,19 @@
                 "module": "utils/mixins/FormInternalsMixin.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "shadowRootOptions",
+              "type": {
+                "text": "object"
+              },
+              "static": true,
+              "default": "{ ...FormfieldWrapper.shadowRootOptions, delegatesFocus: true }",
+              "inheritedFrom": {
+                "name": "Input",
+                "module": "components/input/input.component.js"
+              }
+            },
             {
               "kind": "field",
               "name": "size",
@@ -38195,6 +38213,19 @@
                 "module": "utils/mixins/FormInternalsMixin.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "shadowRootOptions",
+              "type": {
+                "text": "object"
+              },
+              "static": true,
+              "default": "{ ...FormfieldWrapper.shadowRootOptions, delegatesFocus: true }",
+              "inheritedFrom": {
+                "name": "Input",
+                "module": "components/input/input.component.js"
+              }
+            },
             {
               "kind": "field",
               "name": "size",

package/dist/react/screenreaderannouncer/index.d.ts

@@ -4,6 +4,9 @@ import Component from '../../components/screenreaderannouncer';
  *
  * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.
  *
+ * Consumers can also use the public `announce` function to trigger announcements programmatically
+ * by passing an options object where `announcement` is required and all other fields are optional.
+ *
  * **Internal logic**
  *
  * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not
@@ -11,9 +14,25 @@ import Component from '../../components/screenreaderannouncer';
  * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element
  * is created in the DOM.
  *
+ * If you provide a custom `identity`, you must ensure that the element exists and is visually hidden.
+ *
+ * Example CSS:
+ *
+ * ```css
+ * #your-custom-announcer-id {
+ *   clip: rect(0 0 0 0);
+ *   clip-path: inset(50%);
+ *   height: 1px;
+ *   overflow: hidden;
+ *   position: absolute;
+ *   white-space: nowrap;
+ *   width: 1px;
+ * }
+ * ```
+ *
  * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with
  * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.
- * After delay of `delay` milliseconds, a <p> element with the announcement text is appended to the `<div>` element.
+ * After delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.
  *
  * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.
  *
@@ -23,6 +42,10 @@ import Component from '../../components/screenreaderannouncer';
  * **Note**
  * 1. The default delay of 150 miliseconds is used as we dynamically generate the
  * aria-live region in the DOM and add the announcement text to it.
+ * 2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`
+ * for that identity is effectively determined by the first instance that creates announcements for it.
+ * Changing `data-aria-live` in later instances for the same identity will not update already-created
+ * live-region containers.
  * 3. If no `identity` is provided, all the screen reader components will create and use only one
  * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.
  *

package/dist/react/screenreaderannouncer/index.js

@@ -7,6 +7,9 @@ import { TAG_NAME } from '../../components/screenreaderannouncer/screenreaderann
  *
  * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.
  *
+ * Consumers can also use the public `announce` function to trigger announcements programmatically
+ * by passing an options object where `announcement` is required and all other fields are optional.
+ *
  * **Internal logic**
  *
  * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not
@@ -14,9 +17,25 @@ import { TAG_NAME } from '../../components/screenreaderannouncer/screenreaderann
  * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element
  * is created in the DOM.
  *
+ * If you provide a custom `identity`, you must ensure that the element exists and is visually hidden.
+ *
+ * Example CSS:
+ *
+ * ```css
+ * #your-custom-announcer-id {
+ *   clip: rect(0 0 0 0);
+ *   clip-path: inset(50%);
+ *   height: 1px;
+ *   overflow: hidden;
+ *   position: absolute;
+ *   white-space: nowrap;
+ *   width: 1px;
+ * }
+ * ```
+ *
  * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with
  * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.
- * After delay of `delay` milliseconds, a <p> element with the announcement text is appended to the `<div>` element.
+ * After delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.
  *
  * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.
  *
@@ -26,6 +45,10 @@ import { TAG_NAME } from '../../components/screenreaderannouncer/screenreaderann
  * **Note**
  * 1. The default delay of 150 miliseconds is used as we dynamically generate the
  * aria-live region in the DOM and add the announcement text to it.
+ * 2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`
+ * for that identity is effectively determined by the first instance that creates announcements for it.
+ * Changing `data-aria-live` in later instances for the same identity will not update already-created
+ * live-region containers.
  * 3. If no `identity` is provided, all the screen reader components will create and use only one
  * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@momentum-design/components",
   "packageManager": "yarn@3.2.4",
-  "version": "0.131.4",
+  "version": "0.131.6",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=8.0.0"