@4site/engrid-scripts 0.27.2 → 0.27.4

package/dist/a11y.d.ts

@@ -1,9 +1,11 @@
 export declare class A11y {
     private logger;
     private observer;
+    private liveRegionUpdateTimeout;
+    private shouldFocusFirstInvalidField;
     constructor();
     /**
-     * Apply the field-level accessibility tagging (error alert live regions,
+     * Apply the field-level accessibility tagging (error containers,
      * aria-required, fallback aria-labels, radio group roles) to every field
      * within `root`. Defaults to the whole document on initial load, but can be
      * pointed at a freshly injected fragment (e.g. a Supporter Hub overlay) so
@@ -11,22 +13,23 @@ export declare class A11y {
      * idempotent, so re-scanning already tagged fields is safe.
      */
     static scanFields(root?: ParentNode): void;
-    private static addErrorAlertArea;
+    private static addGlobalErrorLiveRegion;
     private static addGroupRole;
     private static addRequired;
     private static addLabel;
     private updateFrequencyLabel;
     private setAutoGeneratedAltTags;
     /**
-     * Observe #engrid for .en__field__error additions and removals, mirroring
-     * text into the per-field .en__field__error__alert live region and toggling
-     * aria-invalid / aria-describedby on the corresponding input. Runs for the
-     * lifetime of the page so async validators (NeverBounce, VGS, server
-     * re-renders) are caught without timing assumptions.
+     * Observe #engrid for .en__field__error additions and removals, relocating
+     * each error after its field's input so DOM order matches visual order. Also
+     * toggles aria-invalid / aria-describedby on the corresponding input (or radio
+     * group when the field has role="group") and updates a single, DOM-ordered
+     * global live region. Runs for the lifetime of the page so async validators
+     * (NeverBounce, VGS, server re-renders) are caught without timing assumptions.
      */
     private observeErrorMessages;
-    private moveErrorMessage;
-    private clearErrorMessage;
+    private tagFieldError;
+    private clearFieldError;
     /**
      * Make everything on the page inert except the supplied overlay element and
      * its ancestors. This hides background content from assistive technology and
@@ -40,5 +43,10 @@ export declare class A11y {
      *                `inert` is true; ignored when `inert` is false.
      */
     static inertPage(inert: boolean, overlay?: HTMLElement): void;
-    private manageErrorListAlertRole;
+    private scheduleLiveRegionUpdate;
+    private updateGlobalErrorLiveRegion;
+    private formatErrorMessage;
+    private focusFirstInvalidField;
+    private getFieldLabel;
+    private normalizeLabel;
 }

package/dist/a11y.js

@@ -1,19 +1,32 @@
 import { EngridLogger } from "./logger";
+import { ENGrid } from "./engrid";
+import { EnForm } from "./events/en-form";
 // a11y means accessibility
 // This Component is supposed to be used as a helper for Aria Attributes & Other Accessibility Features
 export class A11y {
     constructor() {
+        var _a;
         this.logger = new EngridLogger("A11y", "#FFFFFF", "#811212", "👁️‍🗨️");
         this.observer = null;
+        this.liveRegionUpdateTimeout = null;
+        this.shouldFocusFirstInvalidField = false;
         A11y.scanFields();
         this.updateFrequencyLabel();
         const ecardImages = document.querySelectorAll('.en__ecarditems__list img');
         this.setAutoGeneratedAltTags(ecardImages);
-        this.manageErrorListAlertRole();
         this.observeErrorMessages();
+        (_a = ENGrid.enForm) === null || _a === void 0 ? void 0 : _a.addEventListener('submit', () => {
+            this.shouldFocusFirstInvalidField = true;
+        });
+        // onSubmit only fires once validation has passed, so disarm the focus
+        // flag: a successful submit must not leave it set, or the next unrelated
+        // async field error (e.g. NeverBounce on blur) would steal focus.
+        EnForm.getInstance().onSubmit.subscribe(() => {
+            this.shouldFocusFirstInvalidField = false;
+        });
     }
     /**
-     * Apply the field-level accessibility tagging (error alert live regions,
+     * Apply the field-level accessibility tagging (error containers,
      * aria-required, fallback aria-labels, radio group roles) to every field
      * within `root`. Defaults to the whole document on initial load, but can be
      * pointed at a freshly injected fragment (e.g. a Supporter Hub overlay) so
@@ -21,24 +34,29 @@ export class A11y {
      * idempotent, so re-scanning already tagged fields is safe.
      */
     static scanFields(root = document) {
-        A11y.addErrorAlertArea(root);
+        A11y.addGlobalErrorLiveRegion(root);
         A11y.addRequired(root);
         A11y.addLabel(root);
         A11y.addGroupRole(root);
     }
-    static addErrorAlertArea(root = document) {
-        const fieldElements = root.querySelectorAll('.en__field .en__field__element');
-        fieldElements.forEach((fieldElement) => {
-            const fieldWrapper = fieldElement.closest('.en__field');
-            if (fieldWrapper === null || fieldWrapper === void 0 ? void 0 : fieldWrapper.querySelector('.en__field__error__alert'))
-                return;
-            const errorAlert = document.createElement('div');
-            errorAlert.setAttribute('aria-live', 'polite');
-            errorAlert.setAttribute('aria-atomic', 'true');
-            errorAlert.classList.add('en__field__error__alert');
-            errorAlert.id = `en__field__error__alert--${Math.random().toString(36).slice(2, 7)}`;
-            fieldElement.insertAdjacentElement('afterend', errorAlert);
-        });
+    static addGlobalErrorLiveRegion(root = document) {
+        var _a;
+        const liveRegionId = 'engrid-a11y-error-summary';
+        if (document.getElementById(liveRegionId))
+            return;
+        const form = (_a = ENGrid.enForm) !== null && _a !== void 0 ? _a : root.querySelector('form.en__component');
+        if (!form)
+            return;
+        const region = document.createElement('div');
+        region.id = liveRegionId;
+        region.className = 'engrid__sr-only';
+        region.setAttribute('aria-live', 'polite');
+        region.setAttribute('aria-atomic', 'true');
+        form.insertBefore(region, form.firstChild);
+        const errorList = document.querySelector('ul.en__errorList');
+        if (errorList === null || errorList === void 0 ? void 0 : errorList.hasAttribute('role')) {
+            errorList.removeAttribute('role');
+        }
     }
     static addGroupRole(root = document) {
         // Add role="group" to all EN Radio fields
@@ -52,6 +70,13 @@ export class A11y {
             const label = field.querySelector("label");
             if (label) {
                 label.setAttribute("id", `en__field__label--${Math.random().toString(36).slice(2, 7)}`);
+                // EN renders the group's question label as a <label>, but a radio group
+                // has no single control for `for` to point at. When EN leaves it blank
+                // (`for=""`) it's an invalid IDREF, so strip only that empty case
+                const forAttr = label.getAttribute("for");
+                if (forAttr !== null && forAttr.trim() === "") {
+                    label.removeAttribute("for");
+                }
                 field.setAttribute("aria-labelledby", label.id);
             }
         });
@@ -128,11 +153,12 @@ export class A11y {
         });
     }
     /**
-     * Observe #engrid for .en__field__error additions and removals, mirroring
-     * text into the per-field .en__field__error__alert live region and toggling
-     * aria-invalid / aria-describedby on the corresponding input. Runs for the
-     * lifetime of the page so async validators (NeverBounce, VGS, server
-     * re-renders) are caught without timing assumptions.
+     * Observe #engrid for .en__field__error additions and removals, relocating
+     * each error after its field's input so DOM order matches visual order. Also
+     * toggles aria-invalid / aria-describedby on the corresponding input (or radio
+     * group when the field has role="group") and updates a single, DOM-ordered
+     * global live region. Runs for the lifetime of the page so async validators
+     * (NeverBounce, VGS, server re-renders) are caught without timing assumptions.
      */
     observeErrorMessages() {
         var _a;
@@ -143,22 +169,22 @@ export class A11y {
                     continue;
                 record.addedNodes.forEach(node => {
                     if (node instanceof HTMLElement && node.classList.contains('en__field__error')) {
-                        this.moveErrorMessage(node);
+                        this.tagFieldError(node);
                     }
                 });
                 record.removedNodes.forEach(node => {
-                    var _a, _b;
                     if (!(node instanceof HTMLElement))
                         return;
                     if (!node.classList.contains('en__field__error'))
                         return;
+                    if (node.isConnected)
+                        return; // relocated, not removed
                     // node.parentElement is null after removal; record.target is the
                     // former parent. Walk up to the enclosing .en__field to be defensive
                     // against deeper nesting.
-                    const fieldWrapper = (_b = (_a = record.target).closest) === null || _b === void 0 ? void 0 : _b.call(_a, '.en__field');
-                    const alert = fieldWrapper === null || fieldWrapper === void 0 ? void 0 : fieldWrapper.querySelector('.en__field__error__alert');
-                    if (alert)
-                        this.clearErrorMessage(alert);
+                    const fieldWrapper = record.target.closest('.en__field');
+                    if (fieldWrapper)
+                        this.clearFieldError(fieldWrapper, node.id);
                 });
             }
         });
@@ -167,55 +193,76 @@ export class A11y {
         // before this observer was attached.
         document.querySelectorAll('.en__field').forEach(field => {
             const error = field.querySelector('.en__field__error');
-            const alert = field.querySelector('.en__field__error__alert');
             if (error)
-                this.moveErrorMessage(error);
-            else if (alert)
-                this.clearErrorMessage(alert);
+                this.tagFieldError(error);
         });
     }
-    moveErrorMessage(field) {
+    tagFieldError(error) {
         var _a;
-        if (field.closest('.en__field__error__alert'))
-            return;
-        const fieldWrapper = field.closest('.en__field');
+        const fieldWrapper = error.closest('.en__field');
         if (!fieldWrapper)
             return;
-        const alertContainer = fieldWrapper.querySelector('.en__field__error__alert');
-        if (!alertContainer)
-            return;
-        alertContainer.textContent = field.textContent;
-        field.classList.add('en__field__error--hidden-by-a11y');
-        const inputElement = fieldWrapper.querySelector('.en__field__element input, .en__field__element select, .en__field__element textarea');
-        if (!inputElement)
+        const fieldElement = fieldWrapper.querySelector('.en__field__element');
+        if (fieldElement && fieldElement.nextElementSibling !== error) {
+            fieldElement.insertAdjacentElement('afterend', error);
+        }
+        if (!error.id) {
+            error.id = `en__field__error--a11y-${Math.random().toString(36).slice(2, 7)}`;
+        }
+        this.scheduleLiveRegionUpdate();
+        const target = fieldWrapper.getAttribute('role') === 'group'
+            ? fieldWrapper
+            : fieldWrapper.querySelector('.en__field__element input, .en__field__element select, .en__field__element textarea');
+        if (!target)
             return;
-        inputElement.setAttribute('aria-invalid', 'true');
-        const describedBy = ((_a = inputElement.getAttribute('aria-describedby')) !== null && _a !== void 0 ? _a : '')
+        target.setAttribute('aria-invalid', 'true');
+        const describedBy = ((_a = target.getAttribute('aria-describedby')) !== null && _a !== void 0 ? _a : '')
             .split(/\s+/)
             .filter(Boolean);
-        if (describedBy.indexOf(alertContainer.id) === -1) {
-            describedBy.push(alertContainer.id);
+        if (describedBy.indexOf(error.id) === -1) {
+            describedBy.push(error.id);
+        }
+        target.setAttribute('aria-describedby', describedBy.join(' '));
+        // For radio groups, the group itself is the accessible widget; keep the
+        // individual inputs from also being announced as invalid.
+        if (target === fieldWrapper) {
+            fieldWrapper
+                .querySelectorAll('.en__field__element input, .en__field__element select, .en__field__element textarea')
+                .forEach(input => {
+                var _a;
+                input.removeAttribute('aria-invalid');
+                const remaining = ((_a = input.getAttribute('aria-describedby')) !== null && _a !== void 0 ? _a : '')
+                    .split(/\s+/)
+                    .filter(id => id && id !== error.id);
+                if (remaining.length) {
+                    input.setAttribute('aria-describedby', remaining.join(' '));
+                }
+                else {
+                    input.removeAttribute('aria-describedby');
+                }
+            });
         }
-        inputElement.setAttribute('aria-describedby', describedBy.join(' '));
     }
-    clearErrorMessage(alert) {
+    clearFieldError(fieldWrapper, errorId) {
         var _a;
-        alert.textContent = '';
-        const fieldWrapper = alert.closest('.en__field');
-        if (!fieldWrapper)
-            return;
-        const inputElement = fieldWrapper.querySelector('.en__field__element input, .en__field__element select, .en__field__element textarea');
-        if (!inputElement)
+        this.scheduleLiveRegionUpdate();
+        const target = fieldWrapper.getAttribute('role') === 'group'
+            ? fieldWrapper
+            : fieldWrapper.querySelector('.en__field__element input, .en__field__element select, .en__field__element textarea');
+        if (!target)
             return;
-        inputElement.removeAttribute('aria-invalid');
-        const remaining = ((_a = inputElement.getAttribute('aria-describedby')) !== null && _a !== void 0 ? _a : '')
+        const hasRemainingError = fieldWrapper.querySelector('.en__field__error') !== null;
+        if (!hasRemainingError) {
+            target.removeAttribute('aria-invalid');
+        }
+        const remaining = ((_a = target.getAttribute('aria-describedby')) !== null && _a !== void 0 ? _a : '')
             .split(/\s+/)
-            .filter(id => id && id !== alert.id);
+            .filter(id => id && id !== errorId);
         if (remaining.length) {
-            inputElement.setAttribute('aria-describedby', remaining.join(' '));
+            target.setAttribute('aria-describedby', remaining.join(' '));
         }
         else {
-            inputElement.removeAttribute('aria-describedby');
+            target.removeAttribute('aria-describedby');
         }
     }
     /**
@@ -259,29 +306,108 @@ export class A11y {
             });
         }
     }
-    manageErrorListAlertRole() {
+    scheduleLiveRegionUpdate() {
+        if (this.liveRegionUpdateTimeout !== null) {
+            window.clearTimeout(this.liveRegionUpdateTimeout);
+        }
+        this.liveRegionUpdateTimeout = window.setTimeout(() => {
+            this.liveRegionUpdateTimeout = null;
+            this.updateGlobalErrorLiveRegion();
+        }, 100);
+    }
+    updateGlobalErrorLiveRegion() {
+        var _a;
+        const region = document.getElementById('engrid-a11y-error-summary');
+        if (!region)
+            return;
         const errorList = document.querySelector('ul.en__errorList');
-        if (!errorList)
+        if (errorList === null || errorList === void 0 ? void 0 : errorList.hasAttribute('role')) {
+            errorList.removeAttribute('role');
+        }
+        const fields = Array.from(document.querySelectorAll('.en__field'));
+        const messages = fields
+            .map(field => {
+            var _a;
+            const error = field.querySelector('.en__field__error');
+            if (!((_a = error === null || error === void 0 ? void 0 : error.textContent) === null || _a === void 0 ? void 0 : _a.trim()))
+                return null;
+            const label = this.getFieldLabel(field);
+            const message = this.formatErrorMessage(label, error.textContent.trim());
+            return message;
+        })
+            .filter((message) => Boolean(message));
+        // Top-of-form server errors (ul.en__errorList) aren't tied to a .en__field,
+        // so fold in any that aren't already covered by the per-field messages,
+        // otherwise they would be silent for screen readers.
+        const normalizeForCompare = (value) => value.replace(/\s+/g, ' ').replace(/[.!?:]+$/, '').trim().toLowerCase();
+        const coveredMessages = messages.map(normalizeForCompare).filter(Boolean);
+        const serverMessages = Array.from((_a = errorList === null || errorList === void 0 ? void 0 : errorList.querySelectorAll('li')) !== null && _a !== void 0 ? _a : [])
+            .map(item => { var _a, _b; return (_b = (_a = item.textContent) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : ''; })
+            .filter(text => {
+            if (!text)
+                return false;
+            const normalized = normalizeForCompare(text);
+            if (!normalized)
+                return false;
+            return !coveredMessages.some(covered => covered === normalized ||
+                covered.includes(normalized) ||
+                normalized.includes(covered));
+        });
+        const allMessages = [...messages, ...serverMessages];
+        region.textContent = '';
+        if (!allMessages.length) {
+            this.shouldFocusFirstInvalidField = false;
             return;
-        const hasErrorItems = () => Boolean(errorList.querySelector('li'));
-        const enableAlert = () => {
-            if (!errorList.hasAttribute('role')) {
-                errorList.setAttribute('role', 'alert');
-            }
-        };
-        const disableAlert = () => {
-            if (errorList.hasAttribute('role')) {
-                errorList.removeAttribute('role');
-            }
-        };
-        hasErrorItems() ? enableAlert() : disableAlert();
-        new MutationObserver(records => {
-            for (const record of records) {
-                if (record.type === 'childList') {
-                    hasErrorItems() ? enableAlert() : disableAlert();
-                    break;
-                }
+        }
+        if (allMessages.length === 1) {
+            region.textContent = allMessages[0];
+        }
+        else {
+            const cleaned = allMessages.map(message => message.replace(/[.!?]+$/, '').trim());
+            region.textContent = `There are ${allMessages.length} errors: ${cleaned.join('. ')}.`;
+        }
+        if (this.shouldFocusFirstInvalidField) {
+            this.shouldFocusFirstInvalidField = false;
+            this.focusFirstInvalidField();
+        }
+    }
+    formatErrorMessage(label, message) {
+        const cleanMessage = message.trim();
+        const cleanLabel = this.normalizeLabel(label);
+        if (!cleanLabel)
+            return cleanMessage;
+        // If the message already mentions the field label, no need to prefix it.
+        const escapedLabel = cleanLabel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const labelRegex = new RegExp(`\\b${escapedLabel}\\b`, 'i');
+        if (labelRegex.test(cleanMessage))
+            return cleanMessage;
+        return `${cleanLabel}: ${cleanMessage}`;
+    }
+    focusFirstInvalidField() {
+        const fields = Array.from(document.querySelectorAll('.en__field'));
+        for (const field of fields) {
+            if (!field.querySelector('.en__field__error'))
+                continue;
+            const target = field.querySelector('.en__field__element input:not([type="hidden"]), .en__field__element select, .en__field__element textarea');
+            if (target && target.offsetParent !== null && !target.hasAttribute('disabled')) {
+                target.focus();
+                return;
             }
-        }).observe(errorList, { childList: true });
+        }
+    }
+    getFieldLabel(field) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const label = (_c = (_b = (_a = field.querySelector('.en__field__label:not(.en__field__label--item)')) !== null && _a !== void 0 ? _a : field.querySelector('.en__field__label')) !== null && _b !== void 0 ? _b : field.querySelector('label')) !== null && _c !== void 0 ? _c : field.querySelector('legend');
+        const labelText = (_e = (_d = label === null || label === void 0 ? void 0 : label.textContent) === null || _d === void 0 ? void 0 : _d.trim()) !== null && _e !== void 0 ? _e : '';
+        if (labelText)
+            return this.normalizeLabel(labelText);
+        const input = field.querySelector('input, select, textarea');
+        return (_g = (_f = input === null || input === void 0 ? void 0 : input.getAttribute('aria-label')) === null || _f === void 0 ? void 0 : _f.trim()) !== null && _g !== void 0 ? _g : '';
+    }
+    normalizeLabel(label) {
+        return label
+            .replace(/\s+/g, ' ')
+            .replace(/^[*:\s]+|[*:\s]+$/g, '')
+            .trim();
     }
 }

package/dist/frequency-upsell-modal.d.ts

@@ -3,7 +3,7 @@ export declare class FrequencyUpsellModal extends Modal {
     private readonly upsellOptions;
     private _amountWithFees;
     private _upsellAmountWithFees;
-    constructor(upsellOptions: FrequencyUpsellOptions);
+    constructor(upsellOptions: FrequencyUpsellOptions, onDismiss?: () => void);
     set amountWithFees(value: number);
     set upsellAmountWithFees(value: number);
     updateModalContent(): void;

package/dist/frequency-upsell-modal.js

@@ -5,11 +5,12 @@
  */
 import { ENGrid, Modal } from ".";
 export class FrequencyUpsellModal extends Modal {
-    constructor(upsellOptions) {
+    constructor(upsellOptions, onDismiss) {
         super({
             onClickOutside: "bounce",
             customClass: `engrid--frequency-upsell-modal ${upsellOptions.customClass}`,
-            showCloseX: false,
+            showCloseX: upsellOptions.showCloseX,
+            onDismiss,
         });
         this._amountWithFees = 0;
         this._upsellAmountWithFees = 0;

package/dist/frequency-upsell.d.ts

@@ -31,6 +31,11 @@ export declare class FrequencyUpsell {
      */
     getUpsellAmount(withFee: boolean): number;
     private addEventListeners;
+    /**
+     * Handle the modal being dismissed via the X button, Esc key, or click-outside.
+     * This always counts as a decline (onDecline fires either way).
+     */
+    private handleModalDismiss;
     /**
      * Create the frequency field for the upsell, if it does not exist on the page already
      * This is required by DonationFrequency to set the frequency

package/dist/frequency-upsell.js

@@ -23,7 +23,7 @@ export class FrequencyUpsell {
         }
         this.options = this.selectOptions(window.EngridFrequencyUpsell);
         this.logger.log("FrequencyUpsell initialized", this.options);
-        this.upsellModal = new FrequencyUpsellModal(this.options);
+        this.upsellModal = new FrequencyUpsellModal(this.options, () => this.handleModalDismiss());
         this.createFrequencyField();
         this.addEventListeners();
     }
@@ -144,6 +144,20 @@ export class FrequencyUpsell {
             return true;
         });
     }
+    /**
+     * Handle the modal being dismissed via the X button, Esc key, or click-outside.
+     * This always counts as a decline (onDecline fires either way).
+     */
+    handleModalDismiss() {
+        this.logger.log("Frequency upsell modal dismissed (declined)");
+        this.options.onDecline();
+        if (this.options.submitOnClose) {
+            this._form.submitForm();
+        }
+        else {
+            this._form.dispatchError();
+        }
+    }
     /**
      * Create the frequency field for the upsell, if it does not exist on the page already
      * This is required by DonationFrequency to set the frequency

package/dist/interfaces/frequency-upsell-options.d.ts

@@ -10,6 +10,8 @@ export interface FrequencyUpsellOptions {
     onOpen: () => void;
     onAccept: () => void;
     onDecline: () => void;
+    showCloseX: boolean;
+    submitOnClose: boolean;
 }
 export interface FrequencyUpsellABTestConfig {
     abTest: true;

package/dist/interfaces/frequency-upsell-options.js

@@ -10,4 +10,6 @@ export const FrequencyUpsellOptionsDefaults = {
     onOpen: () => { },
     onAccept: () => { },
     onDecline: () => { },
+    showCloseX: false,
+    submitOnClose: false,
 };

package/dist/modal.d.ts

@@ -4,6 +4,8 @@ interface ModalOptions {
     closeButtonLabel?: string;
     customClass?: string;
     showCloseX?: boolean;
+    closeOnEsc?: boolean;
+    onDismiss?: () => void;
 }
 export declare abstract class Modal {
     modalContent: NodeListOf<Element> | HTMLElement | String;
@@ -13,7 +15,14 @@ export declare abstract class Modal {
     protected constructor(options: ModalOptions);
     private createModal;
     private addEventListeners;
+    /**
+     * Generic entry point for dismissing the modal.
+     * Fires the onDismiss callback before closing, so consumers can react to the modal being
+     * dismissed rather than closed via their own explicit button logic.
+     */
+    private dismiss;
     private focusTrapHandler;
+    private escKeyHandler;
     open(): void;
     close(): void;
     getModalContent(): NodeListOf<Element> | HTMLElement | String;

package/dist/modal.js

@@ -8,6 +8,8 @@ export class Modal {
             closeButtonLabel: "Okay!",
             customClass: "",
             showCloseX: true,
+            closeOnEsc: true,
+            onDismiss: () => { },
         };
         this.focusTrapHandler = (e) => {
             const modalElement = this.modal;
@@ -33,6 +35,11 @@ export class Modal {
                 }
             }
         };
+        this.escKeyHandler = (e) => {
+            if (e.key === "Escape" && this.options.closeOnEsc) {
+                this.dismiss();
+            }
+        };
         this.options = Object.assign(Object.assign({}, this.defaultOptions), options);
         this.modalContent = this.getModalContent();
         this.createModal();
@@ -83,7 +90,7 @@ export class Modal {
             button.classList.add("engrid-modal__button");
             button.textContent = this.options.closeButtonLabel;
             button.addEventListener("click", () => {
-                this.close();
+                this.dismiss();
             });
             modalBody === null || modalBody === void 0 ? void 0 : modalBody.appendChild(button);
         }
@@ -93,13 +100,13 @@ export class Modal {
         var _a, _b, _c, _d, _e;
         // Close event on top X
         (_b = (_a = this.modal) === null || _a === void 0 ? void 0 : _a.querySelector(".engrid-modal__close")) === null || _b === void 0 ? void 0 : _b.addEventListener("click", () => {
-            this.close();
+            this.dismiss();
         });
         // Bounce scale when clicking outside of modal
         (_d = (_c = this.modal) === null || _c === void 0 ? void 0 : _c.querySelector(".engrid-modal__overlay")) === null || _d === void 0 ? void 0 : _d.addEventListener("click", (event) => {
             if (event.target === event.currentTarget) {
                 if (this.options.onClickOutside === "close") {
-                    this.close();
+                    this.dismiss();
                 }
                 else if (this.options.onClickOutside === "bounce") {
                     const modal = document.querySelector(".engrid-modal");
@@ -115,25 +122,37 @@ export class Modal {
         const closeEls = (_e = this.modal) === null || _e === void 0 ? void 0 : _e.querySelectorAll(".modal__close");
         closeEls === null || closeEls === void 0 ? void 0 : closeEls.forEach((el) => {
             el.addEventListener("click", () => {
-                this.close();
+                this.dismiss();
             });
         });
     }
+    /**
+     * Generic entry point for dismissing the modal.
+     * Fires the onDismiss callback before closing, so consumers can react to the modal being
+     * dismissed rather than closed via their own explicit button logic.
+     */
+    dismiss() {
+        var _a, _b;
+        (_b = (_a = this.options).onDismiss) === null || _b === void 0 ? void 0 : _b.call(_a);
+        this.close();
+    }
     open() {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         ENGrid.setBodyData("has-lightbox", "true");
         (_a = this.modal) === null || _a === void 0 ? void 0 : _a.classList.remove("modal--hidden");
         (_b = this.modal) === null || _b === void 0 ? void 0 : _b.removeAttribute("aria-hidden");
         const container = (_c = this.modal) === null || _c === void 0 ? void 0 : _c.querySelector(".engrid-modal__container");
         container === null || container === void 0 ? void 0 : container.focus({ preventScroll: true });
         (_d = this.modal) === null || _d === void 0 ? void 0 : _d.addEventListener("keydown", this.focusTrapHandler);
+        (_e = this.modal) === null || _e === void 0 ? void 0 : _e.addEventListener("keydown", this.escKeyHandler);
     }
     close() {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         ENGrid.setBodyData("has-lightbox", false);
         (_a = this.modal) === null || _a === void 0 ? void 0 : _a.classList.add("modal--hidden");
         (_b = this.modal) === null || _b === void 0 ? void 0 : _b.setAttribute("aria-hidden", "true");
         (_c = this.modal) === null || _c === void 0 ? void 0 : _c.removeEventListener("keydown", this.focusTrapHandler);
+        (_d = this.modal) === null || _d === void 0 ? void 0 : _d.removeEventListener("keydown", this.escKeyHandler);
     }
     getModalContent() {
         return "<h1>Default Modal Content</h1>";

package/dist/page-background.d.ts

@@ -1,3 +1,8 @@
+declare global {
+    interface Window {
+        UseBodyBannerImageAsBackground?: boolean;
+    }
+}
 export declare class PageBackground {
     private pageBackground;
     private bodyBanner;

package/dist/page-background.js

@@ -7,6 +7,9 @@ export class PageBackground {
         this.bodyBannerImage = null;
         this.mutationObserver = null;
         this.logger = new EngridLogger("PageBackground", "lightblue", "darkblue", "🖼️");
+        if (typeof window.UseBodyBannerImageAsBackground !== "undefined") {
+            useBodyBannerImage = !!window.UseBodyBannerImageAsBackground;
+        }
         if (useBodyBannerImage) {
             this.bodyBannerImage = this.findBodyBannerImage();
         }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const AppVersion = "0.27.2";
+export declare const AppVersion = "0.27.4";

package/dist/version.js

@@ -1 +1 @@
-export const AppVersion = "0.27.2";
+export const AppVersion = "0.27.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4site/engrid-scripts",
-  "version": "0.27.2",
+  "version": "0.27.4",
   "description": "Scripts for the ENGRID Project",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,7 +25,7 @@
     "strongly-typed-events": "^2.0.9"
   },
   "homepage": "https://github.com/4site-interactive-studios/engrid#readme",
-  "gitHead": "12d807e7827704b485c0ce1b99e81b1e957362e8",
+  "gitHead": "e01ad2b4ea0b53edda39388f6597976e33e5f129",
   "devDependencies": {
     "nodemon": "^2.0.20"
   }