@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/collection/components/wm-modal/wm-modal.js

@@ -0,0 +1,534 @@
+import { h } from "@stencil/core";
+import { generateId } from "../../global/functions";
+/**
+ * Modal dialog that overlays the page. Renders as a full-bleed `modal` (default) or a
+ * smaller centered `dialog`. Content is provided through wm-modal-header, wm-modal-footer,
+ * and arbitrary slotted children.
+ *
+ * @category Communication
+ * @displayName Modal & Dialog
+ *
+ * @slot - Modal content: wm-modal-header, body content, and wm-modal-footer.
+ *
+ * @keyboardInteraction
+ * - **Tab**: Advances focus through focusable elements; wraps from the last element back to the first.
+ * - **Shift+Tab**: Moves focus backward; wraps from the first element to the last.
+ * - **Escape**: Fires `wmModalCloseTriggered` (the host application must set `open = false` on the element ref in response).
+ * - **Enter / Space**: Activates the focused button.
+ *
+ * @accessibility
+ * - Rendered as a `<dialog>` element with `aria-labelledby` pointing to the heading.
+ * - When footer buttons receive initial focus (`element-to-focus="primary"` or `"secondary"`),
+ *   the element `id` on `<wm-modal>` is required — it is used to construct `aria-describedby`
+ *   relationships between the heading, content, and footer.
+ * - The content wrapper must have `id="content-[id of wm-modal]"` for the aria-describedby association.
+ * - Focus returns automatically to the element that was active when the modal opened.
+ *
+ * @usageNotes
+ * - Always render the component and toggle `open` — do not conditionally mount/unmount it.
+ *   Conditional rendering breaks the `aria-live` region detection and can cause body-scroll issues.
+ * - In React, set `open` imperatively via a ref (`ref.current.open = true/false`) rather than
+ *   passing it as a prop. Using the prop triggers a React re-render that interferes with the
+ *   native `<dialog>` focus-return mechanism and causes `:focus-visible` styles to appear on
+ *   the trigger element after close.
+ * - For scrollable modal content, set `overflow: auto` on the content wrapper and reset
+ *   `scrollTop` when reopening a previously scrolled modal.
+ * - On mobile (<768px) with `modal-type="dialog"`, `element-to-focus` targeting a footer button
+ *   is overridden to the close button to avoid disorienting scroll behavior.
+ *
+ * @example {html} Basic modal
+ * <wm-modal id="confirm-modal" open>
+ *   <wm-modal-header heading="Confirm action"></wm-modal-header>
+ *   <div id="content-confirm-modal">Are you sure you want to continue?</div>
+ *   <wm-modal-footer primary-text="Confirm" secondary-text="Cancel"></wm-modal-footer>
+ * </wm-modal>
+ *
+ * @example {react} Basic modal
+ * // Set open imperatively via ref -- do not use open={} as a React prop.
+ * // This preserves the native <dialog> focus-return without triggering :focus-visible.
+ * const modalRef = useRef(null);
+ *
+ * const openModal = () => { modalRef.current.open = true; };
+ * const closeModal = () => { modalRef.current.open = false; };
+ *
+ * <WmButton onClick={openModal}>Open modal</WmButton>
+ *
+ * <WmModal
+ *   ref={modalRef}
+ *   id="confirm-modal"
+ *   onWmModalCloseTriggered={closeModal}
+ *   onWmModalPrimaryTriggered={closeModal}
+ *   onWmModalSecondaryTriggered={closeModal}
+ * >
+ *   <WmModalHeader heading="Confirm action" />
+ *   <div id="content-confirm-modal">Are you sure you want to continue?</div>
+ *   <WmModalFooter primaryText="Confirm" secondaryText="Cancel" />
+ * </WmModal>
+ *
+ * @example {html} Dialog type (smaller, centered)
+ * <wm-modal id="info-dialog" modal-type="dialog" open>
+ *   <wm-modal-header heading="Information"></wm-modal-header>
+ *   <div id="content-info-dialog">This is additional context.</div>
+ *   <wm-modal-footer primary-text="Got it"></wm-modal-footer>
+ * </wm-modal>
+ *
+ * @example {react} Dialog type
+ * const dialogRef = useRef(null);
+ *
+ * const openDialog = () => { dialogRef.current.open = true; };
+ * const closeDialog = () => { dialogRef.current.open = false; };
+ *
+ * <WmButton onClick={openDialog}>Open dialog</WmButton>
+ *
+ * <WmModal
+ *   ref={dialogRef}
+ *   id="info-dialog"
+ *   modalType="dialog"
+ *   onWmModalCloseTriggered={closeDialog}
+ *   onWmModalPrimaryTriggered={closeDialog}
+ * >
+ *   <WmModalHeader heading="Information" />
+ *   <div id="content-info-dialog">This is additional context.</div>
+ *   <WmModalFooter primaryText="Got it" />
+ * </WmModal>
+ *
+ * @requiredSetup
+ * - Drive `open` from your own state: true to show the modal, false to hide it. In React set it
+ *   through a ref (`ref.current.open = true`) rather than as a prop, which breaks the native dialog
+ *   focus-return.
+ * - Handle `wmModalCloseTriggered` -- the close button and Escape -- by setting `open = false`. It
+ *   does not bubble, so attach the listener to the element itself.
+ * - Handle `wmModalPrimaryTriggered` and `wmModalSecondaryTriggered` for whichever wm-modal-footer
+ *   buttons you render, setting `open = false` to dismiss.
+ * - Reset the content wrapper's `scrollTop` to 0 when reopening, if the body content scrolls.
+ *
+ */
+export class Modal {
+    constructor() {
+        this.open = false;
+        this.elementToFocus = "";
+        this.modalType = "modal";
+        this.uid = undefined;
+        this.returnFocusEl = undefined;
+    }
+    get closeButtonEl() {
+        return this.el.querySelector(`#wm-modal-close-${this.uid}`);
+    }
+    get focusOnOpenEl() {
+        let customElementToFocus = null;
+        if (this.elementToFocus === "primary" || this.elementToFocus === "secondary") {
+            if (this.modalType === "dialog" && window.innerWidth < 768) {
+                // When a dialog is opened at this smaller width,
+                // focusing the footer buttons can cause the dialog to scroll and disorient the user
+                customElementToFocus = this.closeButtonEl;
+            }
+            else {
+                customElementToFocus = this.el.querySelector(`#wm-${this.elementToFocus}-${this.uid}`);
+            }
+        }
+        else if (this.elementToFocus) {
+            customElementToFocus = this.el.querySelector("#" + this.elementToFocus);
+            !customElementToFocus &&
+                console.warn(`Ripple Component Library: The modal component couldn't find an element matching the id you passed for 'elementToFocus' (${this.elementToFocus}). It will fall back to the default and focus the close button when the modal opens.`);
+        }
+        return customElementToFocus;
+    }
+    get hasBrowserPopoverSupport() {
+        // For browsers without popover support, render a fallback tooltip inside the dialog so it appears above it
+        return typeof HTMLElement.prototype.showPopover === 'function';
+    }
+    toggleModal() {
+        this.open ? this.showModal() : this.hideModal();
+    }
+    handleDialogClose() {
+        if (this.open) {
+            // if this.open = false, dialog close was prompted by user. Otherwise, dialog close was prompted by dialog element itself
+            // if dialog element was closed by built-in functionality (escape key), make sure closeTriggered event is emitted to keep app state in sync
+            this.wmModalCloseTriggered.emit();
+        }
+        this.open = false;
+    }
+    showModal() {
+        this.returnFocusEl = document.activeElement;
+        this.setAriaDescribedbyOnModal();
+        this.initialBodyOverflow = document.body.style.overflow;
+        document.body.style.overflow = "hidden"; //Keeps the page below the modal from scrolling
+        this.dialogEl.showModal();
+        if (this.focusOnOpenEl) {
+            this.focusOnOpenEl.focus();
+        }
+    }
+    hideModal() {
+        document.body.style.overflow = this.initialBodyOverflow; // TypeScript doesn't like the idea of assigning undefined but that's what we want
+        this.dialogEl.close();
+        // if focus is lost, bring focus to the element which was in focus when modal opened
+        setTimeout(() => {
+            if (this.returnFocusEl && document.activeElement === document.body) {
+                if (this.returnFocusEl.tagName === "WM-MENUITEM") {
+                    this.returnFocusEl = this.returnFocusEl.parentElement;
+                }
+                this.returnFocusEl.focus();
+            }
+        }, 20);
+    }
+    componentWillLoad() {
+        if (this.elementToFocus === "primary" || this.elementToFocus === "secondary") {
+            if (!this.el.id) {
+                console.error("For accessibility purposes you need to set the modal content wrapper's id to 'content-[id of wm-modal]'.");
+            }
+        }
+        this.el.focus = () => {
+            if (this.focusOnOpenEl) {
+                this.focusOnOpenEl.focus();
+            }
+            else {
+                this.closeButtonEl.focus();
+            }
+        };
+        this.uid = this.el.id ? this.el.id : generateId();
+    }
+    componentDidLoad() {
+        if (this.open) {
+            this.showModal();
+        }
+        this.dialogEl.addEventListener("close", () => this.handleDialogClose());
+    }
+    /**
+     * @description Programmatically fires `wmModalCloseTriggered`. Use when you need to trigger
+     * a close from outside the modal without simulating a button click.
+     * @returns A promise that resolves once the event has been emitted.
+     */
+    async emitCloseEvent() {
+        this.wmModalCloseTriggered.emit();
+    }
+    /**
+     * @description Programmatically fires `wmModalPrimaryTriggered`. Use when you need to trigger
+     * the primary action from outside the modal.
+     * @returns A promise that resolves once the event has been emitted.
+     */
+    async emitPrimaryEvent() {
+        this.wmModalPrimaryTriggered.emit();
+    }
+    /**
+     * @description Programmatically fires `wmModalSecondaryTriggered`. Use when you need to trigger
+     * the secondary action from outside the modal.
+     * @returns A promise that resolves once the event has been emitted.
+     */
+    async emitSecondaryEvent() {
+        this.wmModalSecondaryTriggered.emit();
+    }
+    handleKeyDown(ev) {
+        if (ev.key == "Escape") {
+            ev.stopPropagation();
+        }
+    }
+    setAriaDescribedbyOnModal() {
+        const modalBody = document.getElementById(`content-${this.uid}`);
+        if (!modalBody) {
+            console.warn("Ripple Component Library: The element containing the body of the modal must include an id in the format 'content-[id of modal]' for accessibility purposes.");
+        }
+        else {
+            this.el.setAttribute("aria-describedby", `wm-modal-heading-text-${this.uid} content-${this.uid}`);
+        }
+    }
+    render() {
+        return (h("dialog", { key: '995c3ed868be28431fd16f59f42842676fb866dc', class: `${"wm-" + this.modalType}`, "aria-labelledby": `wm-modal-heading-text-${this.uid}`, ref: (el) => (this.dialogEl = el), onKeyDown: (ev) => this.handleKeyDown(ev) }, h("div", { key: 'b70bd7e83d7b89c7878dc8eccb2f6c3744c354b6', class: "tabtrap sr-only", tabindex: "0", onFocus: (ev) => {
+                const focusedFromCloseButton = ev.relatedTarget && ev.relatedTarget == this.closeButtonEl;
+                // no related target means we're coming from outside the page (browser chrome), and first element should be focused instead
+                focusedFromCloseButton ? this.focusLastElement.emit() : this.focusFirstElement.emit();
+            } }), !this.hasBrowserPopoverSupport && h("div", { key: '8153ea292a5d2e92c94bc4851a9558d0e4c15dbe', class: "wm-tooltip" }), h("slot", { key: '1056abeca733388eb293562a213221a8d0434b1a' }), h("div", { key: '961af64369b5a2f4645c472dcde9b4b590593972', class: "tabtrap sr-only", tabindex: "0", onFocus: () => {
+                this.focusFirstElement.emit();
+            } })));
+    }
+    static get is() { return "wm-modal"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-modal.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-modal.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "open": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Controls the open/closed state of the modal. Always render the component and\ntoggle this prop \u2014 do not conditionally mount/unmount."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "open",
+                "reflect": true,
+                "defaultValue": "false"
+            },
+            "elementToFocus": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "\"primary\" | \"secondary\" | string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Element to focus when the modal opens. Pass `\"primary\"` or `\"secondary\"` to\nfocus the corresponding wm-modal-footer button, or an element `id` to focus a specific\nelement in the modal body. Defaults to the close button. Requires `id` to be set on\n`<wm-modal>` when targeting footer buttons."
+                        }, {
+                            "name": "default",
+                            "text": "\"\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "element-to-focus",
+                "reflect": false,
+                "defaultValue": "\"\""
+            },
+            "modalType": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"modal\" | \"dialog\"",
+                    "resolved": "\"dialog\" | \"modal\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visual presentation style. `'modal'` renders a full-bleed overlay; `'dialog'`\nrenders a smaller centered panel."
+                        }, {
+                            "name": "default",
+                            "text": "\"modal\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "modal-type",
+                "reflect": true,
+                "defaultValue": "\"modal\""
+            },
+            "uid": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Unique identifier used internally to wire `aria-labelledby` and\n`aria-describedby` relationships. Set automatically from the element's `id` attribute or\ngenerated if absent \u2014 do not set this prop manually."
+                        }],
+                    "text": ""
+                },
+                "attribute": "uid",
+                "reflect": true
+            }
+        };
+    }
+    static get states() {
+        return {
+            "returnFocusEl": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "focusLastElement",
+                "name": "focusLastElement",
+                "bubbles": false,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal tab-trap signals \u2014 not for application use."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }, {
+                "method": "focusFirstElement",
+                "name": "focusFirstElement",
+                "bubbles": false,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal tab-trap signals \u2014 not for application use."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }, {
+                "method": "wmModalCloseTriggered",
+                "name": "wmModalCloseTriggered",
+                "bubbles": false,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the close button is clicked or Escape is pressed. Does not bubble,\npreventing nested modals from closing simultaneously. The host application must set `open`\nto false in response."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }, {
+                "method": "wmModalPrimaryTriggered",
+                "name": "wmModalPrimaryTriggered",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the wm-modal-footer primary button is clicked."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }, {
+                "method": "wmModalSecondaryTriggered",
+                "name": "wmModalSecondaryTriggered",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the wm-modal-footer secondary button is clicked."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "emitCloseEvent": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": [{
+                            "name": "description",
+                            "text": "Programmatically fires `wmModalCloseTriggered`. Use when you need to trigger\na close from outside the modal without simulating a button click."
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves once the event has been emitted."
+                        }]
+                }
+            },
+            "emitPrimaryEvent": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": [{
+                            "name": "description",
+                            "text": "Programmatically fires `wmModalPrimaryTriggered`. Use when you need to trigger\nthe primary action from outside the modal."
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves once the event has been emitted."
+                        }]
+                }
+            },
+            "emitSecondaryEvent": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": [{
+                            "name": "description",
+                            "text": "Programmatically fires `wmModalSecondaryTriggered`. Use when you need to trigger\nthe secondary action from outside the modal."
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves once the event has been emitted."
+                        }]
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "open",
+                "methodName": "toggleModal"
+            }];
+    }
+}