@momentum-design/components 0.120.25 → 0.120.27

package/dist/components/announcementdialog/announcementdialog.styles.js

@@ -16,7 +16,7 @@ const styles = css `
     background-position: right;
   }
   :host::part(body) {
-    margin-top: 2rem;
+    margin-top: 2rem !important;
     display: grid;
     grid-template-columns: repeat(auto-fit, minmax(0px, 1fr));
   }

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

@@ -66,6 +66,12 @@ declare class ScreenreaderAnnouncer extends Component {
      * @default 20_000
      */
     timeout: number;
+    /**
+     * The debounce time delay in milliseconds for announcements.
+     *
+     * @default 500
+     */
+    debounceTime: number;
     /**
      * Array to store timeOutIds for clearing timeouts later.
      * @internal
@@ -76,6 +82,8 @@ declare class ScreenreaderAnnouncer extends Component {
      * @internal
      */
     private ariaLiveAnnouncementIds;
+    /** @internal */
+    private debouncedAnnounce?;
     /**
      * Announces the given announcement to the screen reader.
      *
@@ -102,6 +110,13 @@ declare class ScreenreaderAnnouncer extends Component {
      * `mdc-screenreaderannouncer-identity`.
      */
     private createAnnouncementAriaLiveRegion;
+    /**
+     * Creates a single debounced function that will read the latest this.announcement when executed.
+     *
+     * This function is used to debounce the announcement so that it will only be made after
+     * this.debounceTime milliseconds have passed since the last time this.announcement was updated.
+     */
+    private setupDebouncedAnnounce;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;

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

@@ -10,6 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 import { property } from 'lit/decorators.js';
 import { v4 as uuidv4 } from 'uuid';
 import { Component } from '../../models';
+import { debounce } from '../../utils/debounce';
 import { DEFAULTS } from './screenreaderannouncer.constants';
 import styles from './screenreaderannouncer.styles';
 /**
@@ -79,6 +80,12 @@ class ScreenreaderAnnouncer extends Component {
          * @default 20_000
          */
         this.timeout = DEFAULTS.TIMEOUT;
+        /**
+         * The debounce time delay in milliseconds for announcements.
+         *
+         * @default 500
+         */
+        this.debounceTime = DEFAULTS.DEBOUNCE;
         /**
          * Array to store timeOutIds for clearing timeouts later.
          * @internal
@@ -109,8 +116,8 @@ class ScreenreaderAnnouncer extends Component {
         if (announcement.length > 0) {
             const announcementId = `mdc-screenreaderannouncer-announcement-${uuidv4()}`;
             const announcementContainer = document.createElement('div');
-            announcementContainer.id = announcementId;
-            announcementContainer.ariaLive = ariaLive;
+            announcementContainer.setAttribute('id', announcementId);
+            announcementContainer.setAttribute('aria-live', ariaLive);
             (_a = document.getElementById(this.identity)) === null || _a === void 0 ? void 0 : _a.appendChild(announcementContainer);
             const timeOutId = window.setTimeout(() => {
                 const announcementElement = document.createElement('p');
@@ -166,25 +173,48 @@ class ScreenreaderAnnouncer extends Component {
             document.body.appendChild(liveRegionLightDom);
         }
     }
+    /**
+     * Creates a single debounced function that will read the latest this.announcement when executed.
+     *
+     * This function is used to debounce the announcement so that it will only be made after
+     * this.debounceTime milliseconds have passed since the last time this.announcement was updated.
+     */
+    setupDebouncedAnnounce() {
+        // create single debounced function that will read latest this.announcement when executed
+        this.debouncedAnnounce = debounce(() => {
+            if (this.announcement.length > 0) {
+                this.announce(this.announcement, this.delay, this.timeout, this.dataAriaLive);
+                this.announcement = '';
+            }
+        }, this.debounceTime);
+    }
     connectedCallback() {
         super.connectedCallback();
         if (this.identity.length === 0) {
             this.identity = DEFAULTS.IDENTITY;
         }
         this.createAnnouncementAriaLiveRegion();
+        this.setupDebouncedAnnounce();
     }
     disconnectedCallback() {
+        var _a;
         super.disconnectedCallback();
         this.clearTimeOutsAndAnnouncements();
+        // cancel any pending debounced action and clear DOM timeouts
+        (_a = this.debouncedAnnounce) === null || _a === void 0 ? void 0 : _a.cancel();
     }
     updated(changedProperties) {
+        var _a;
         if (changedProperties.has('identity') && this.identity.length === 0) {
             this.identity = DEFAULTS.IDENTITY;
             this.createAnnouncementAriaLiveRegion();
         }
+        if (changedProperties.has('debounceTime')) {
+            // Reinitiate debounced function if debounceTime changed
+            this.setupDebouncedAnnounce();
+        }
         if (changedProperties.has('announcement') && this.announcement.length > 0) {
-            this.announce(this.announcement, this.delay, this.timeout, this.dataAriaLive);
-            this.announcement = '';
+            (_a = this.debouncedAnnounce) === null || _a === void 0 ? void 0 : _a.call(this);
         }
     }
 }
@@ -209,4 +239,8 @@ __decorate([
     property({ type: Number, reflect: true }),
     __metadata("design:type", Number)
 ], ScreenreaderAnnouncer.prototype, "timeout", void 0);
+__decorate([
+    property({ type: Number, reflect: true, attribute: 'debounce-time' }),
+    __metadata("design:type", Number)
+], ScreenreaderAnnouncer.prototype, "debounceTime", void 0);
 export default ScreenreaderAnnouncer;

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

@@ -9,5 +9,6 @@ declare const DEFAULTS: {
     readonly DELAY: 150;
     readonly IDENTITY: "mdc-screenreaderannouncer-identity";
     readonly TIMEOUT: 20000;
+    readonly DEBOUNCE: 500;
 };
 export { ARIA_LIVE_VALUES, DEFAULTS, TAG_NAME };

package/dist/components/screenreaderannouncer/screenreaderannouncer.constants.js

@@ -10,5 +10,6 @@ const DEFAULTS = {
     DELAY: 150,
     IDENTITY: 'mdc-screenreaderannouncer-identity',
     TIMEOUT: 20000,
+    DEBOUNCE: 500,
 };
 export { ARIA_LIVE_VALUES, DEFAULTS, TAG_NAME };

package/dist/components/textarea/index.d.ts

@@ -1,6 +1,7 @@
 import Textarea from './textarea.component';
 import '../button';
 import '../icon';
+import '../screenreaderannouncer';
 import '../text';
 import '../toggletip';
 declare global {

package/dist/components/textarea/index.js

@@ -2,6 +2,7 @@ import Textarea from './textarea.component';
 import { TAG_NAME } from './textarea.constants';
 import '../button';
 import '../icon';
+import '../screenreaderannouncer';
 import '../text';
 import '../toggletip';
 Textarea.register(TAG_NAME);

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

@@ -110,14 +110,25 @@ declare class Textarea extends Textarea_base {
      */
     minlength?: number;
     /**
-     * maximum character limit for the textarea field for character counter.
+     * The maximum character limit for the textarea field for character counter.
      */
     maxCharacterLimit?: number;
+    /**
+     * Template string for the announcement that will be read by screen readers when the max character limit is set.
+     * Consumers must use the placeholders `%{number-of-characters}` and `%{max-character-limit}` in the string,
+     * which will be dynamically replaced with the actual values at runtime.
+     * For example: `%{number-of-characters} out of %{max-character-limit} characters are typed.`
+     * Example output: "93 out of 140 characters are typed."
+     */
+    characterLimitAnnouncement?: string;
     /**
      * @internal
      * The textarea element
      */
     inputElement: HTMLTextAreaElement;
+    /** @internal */
+    private ariaLiveAnnouncer?;
+    /** @internal */
     private characterLimitExceedingFired;
     protected get textarea(): HTMLTextAreaElement;
     connectedCallback(): void;
@@ -160,6 +171,12 @@ declare class Textarea extends Textarea_base {
      * @returns void
      */
     private updateValue;
+    /**
+     * Announces the character limit warning based on the current value length.
+     * If the value length exceeds the max character limit, the help text is announced (if help text is present).
+     * If the value length does not exceed the max character limit, then the character limit announcement is announced.
+     */
+    private announceMaxLengthWarning;
     /**
      * Handles the change event of the textarea field.
      * Updates the value and sets the validity of the textarea field.

package/dist/components/textarea/textarea.component.js

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { html, nothing } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
-import { property, query } from 'lit/decorators.js';
+import { property, query, state } from 'lit/decorators.js';
 import FormfieldWrapper from '../formfieldwrapper';
 import { DEFAULTS as FORMFIELD_DEFAULTS, VALIDATION } from '../formfieldwrapper/formfieldwrapper.constants';
 import { AUTO_CAPITALIZE } from '../input/input.constants';
@@ -110,6 +110,7 @@ class Textarea extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMix
          * @default 'off'
          */
         this.autocomplete = AUTO_COMPLETE.OFF;
+        /** @internal */
         this.characterLimitExceedingFired = false;
     }
     get textarea() {
@@ -255,6 +256,33 @@ class Textarea extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMix
     updateValue() {
         this.value = this.textarea.value;
         this.internals.setFormValue(this.textarea.value);
+        this.announceMaxLengthWarning();
+    }
+    /**
+     * Announces the character limit warning based on the current value length.
+     * If the value length exceeds the max character limit, the help text is announced (if help text is present).
+     * If the value length does not exceed the max character limit, then the character limit announcement is announced.
+     */
+    announceMaxLengthWarning() {
+        this.ariaLiveAnnouncer = '';
+        if (!this.maxCharacterLimit || this.value.length === 0) {
+            return;
+        }
+        if (this.helpText && this.value.length > this.maxCharacterLimit) {
+            // We need to assign the same value multiple times, when the input reaches the max limit,
+            // Lit does a `===` strict comparison and doesn't update the value
+            // Hence we need to manually wait for the update to complete and then assign the value.
+            this.updateComplete
+                .then(() => {
+                this.ariaLiveAnnouncer = this.helpText;
+            })
+                .catch(() => { });
+        }
+        else if (this.characterLimitAnnouncement && this.value.length <= this.maxCharacterLimit) {
+            this.ariaLiveAnnouncer = this.characterLimitAnnouncement
+                .replace('%{number-of-characters}', this.value.length.toString())
+                .replace('%{max-character-limit}', this.maxCharacterLimit.toString());
+        }
     }
     /**
      * Handles the change event of the textarea field.
@@ -315,6 +343,11 @@ class Textarea extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMix
           aria-describedby="${ifDefined(this.helpText ? FORMFIELD_DEFAULTS.HELPER_TEXT_ID : '')}"
           aria-invalid="${this.helpTextType === 'error' ? 'true' : 'false'}"
         ></textarea>
+        <mdc-screenreaderannouncer
+          identity="${this.inputId}"
+          announcement="${ifDefined(this.ariaLiveAnnouncer)}"
+          data-aria-live="polite"
+        ></mdc-screenreaderannouncer>
       </div>
       ${this.renderTextareaFooter()}
     `;
@@ -361,8 +394,16 @@ __decorate([
     property({ type: Number, attribute: 'max-character-limit' }),
     __metadata("design:type", Number)
 ], Textarea.prototype, "maxCharacterLimit", void 0);
+__decorate([
+    property({ type: String, attribute: 'character-limit-announcement' }),
+    __metadata("design:type", String)
+], Textarea.prototype, "characterLimitAnnouncement", void 0);
 __decorate([
     query('textarea'),
     __metadata("design:type", HTMLTextAreaElement)
 ], Textarea.prototype, "inputElement", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", String)
+], Textarea.prototype, "ariaLiveAnnouncer", void 0);
 export default Textarea;