@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,363 @@
+import { h, Host } from "@stencil/core";
+import { generateId, hideTooltip, intl, showTooltip } from "../../global/functions";
+import { globalMessages } from "../../global/intl";
+/**
+ * Toast notification stack that renders transient messages at the bottom of the page.
+ * Notifications auto-dismiss after 6 seconds unless they include a `link` or `action`, in
+ * which case they persist until explicitly dismissed or the user tabs past them.
+ *
+ * @category Communication
+ *
+ * @keyboardInteraction
+ * - **Tab**: Moves focus from the action link/button to the close button; tabbing past the
+ *   close button dismisses the notification and returns focus to the previously active element.
+ * - **Shift+Tab**: Dismisses the notification from the action link and returns focus; moves
+ *   from the close button back to the action link.
+ * - **Enter**: Activates the focused close button or action link/button.
+ *
+ * @accessibility
+ * - Renders an `aria-live` region that announces new notification messages to screen readers.
+ * - When a notification includes a `link` or `action` and the user is navigating by keyboard,
+ *   focus moves automatically to the action element when the notification appears.
+ * - Focus returns to the previously active element when the notification is dismissed.
+ *
+ * @usageNotes
+ * - `notifications` is typed as a string — always pass `JSON.stringify(array)` in both HTML
+ *   and React. Passing an array directly causes a "[object Object] is not valid JSON" error.
+ * - Each notification object requires a unique `id` (string) and a `message` (string).
+ *   Optional fields: `link` (string, renders a navigation anchor), `action` (string, renders
+ *   a button), `newWindow` (boolean, adds an "opens in new window" indicator to the link).
+ * - Use `link` for navigation actions and `action` for in-page triggers such as "Undo" —
+ *   both emit `wmSnackbarActionTriggered` when clicked.
+ * - Listen to `wmSnackbarSnackFinished` and remove the matching notification from your array
+ *   to keep state in sync. The 6-second auto-dismiss timer is disabled for notifications
+ *   with a `link` or `action` — remove them manually after the action is handled.
+ * - `wmSnackbarSnackFinished` detail: `{ id: string }`.
+ * - `wmSnackbarActionTriggered` detail: `{ id: string, message: string, action?: string, link?: string }`.
+ *
+ * @example {html} Simple notification
+ * <wm-snackbar notifications='[{"id":"1","message":"Changes saved."}]'></wm-snackbar>
+ *
+ * @example {react} Notification stack with action and link variants
+ * // notifications is typed as string — always pass JSON.stringify(array), never the array directly.
+ * // wmSnackbarSnackFinished fires when a notification auto-dismisses or is closed.
+ * // wmSnackbarActionTriggered fires when the action button or link is clicked;
+ * // remove the notification manually after handling the action.
+ * let nextId = 1;
+ * const [notifications, setNotifications] = useState([]);
+ *
+ * const addNotification = (notification) =>
+ *   setNotifications((prev) => [...prev, { id: String(nextId++), ...notification }]);
+ *
+ * const removeNotification = (id) =>
+ *   setNotifications((prev) => prev.filter((n) => n.id !== id));
+ *
+ * const handleActionTriggered = (e) => {
+ *   const { id, action } = e.detail;
+ *   if (action === "Undo") { handleUndo(); }
+ *   removeNotification(id);
+ * };
+ *
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Changes saved." })}>
+ *   Simple notification
+ * </WmButton>
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Item deleted.", action: "Undo" })}>
+ *   With action
+ * </WmButton>
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Report ready.", link: "#report" })}>
+ *   With link
+ * </WmButton>
+ *
+ * <WmSnackbar
+ *   notifications={JSON.stringify(notifications)}
+ *   onWmSnackbarSnackFinished={(e) => removeNotification(e.detail.id)}
+ *   onWmSnackbarActionTriggered={handleActionTriggered}
+ * />
+ *
+ * @requiredSetup
+ * - Show a snack by adding an entry to `notifications`, and pass the stringified array rather than
+ *   the array itself.
+ * - Handle `wmSnackbarSnackFinished` (`event.detail` is `{ id }`) by removing that entry from the
+ *   array you pass to `notifications`; the component does not remove it for you.
+ * - Handle `wmSnackbarActionTriggered` for entries carrying `link` or `action`, and remove the entry
+ *   yourself once handled -- the 6-second auto-dismiss does not apply to those.
+ *
+ */
+export class Snackbar {
+    constructor() {
+        this.parsedNotifications = [];
+        this.uid = this.el.id ? this.el.id : generateId();
+        this.focusOnDismiss = null;
+        this.timers = {};
+        this.closeSnackMessage = intl.formatMessage({
+            id: "snackbar.closeNotification",
+            defaultMessage: "Close this notification",
+            description: "Notification refers to a notification UI element that can be dismissed",
+        });
+        this.notifications = "[]";
+        this.isTabbing = false;
+        this.announcement = "";
+    }
+    componentDidLoad() {
+        const snackObserver = new MutationObserver((snackMutations) => snackMutations.forEach((mutationRecord) => this.handleSnackMutation(mutationRecord)));
+        snackObserver.observe(this.snackAreaEl, { childList: true });
+    }
+    handleSnackMutation(mutationRecord) {
+        const addedSnacks = Array.from(mutationRecord.addedNodes);
+        if (addedSnacks.length > 0) {
+            addedSnacks.forEach((s) => s.querySelector(".wm-snackbar").classList.add("grow"));
+            addedSnacks[0].scrollIntoView();
+        }
+    }
+    updateSnacks(newValue) {
+        const prevParsedNotifications = [...this.parsedNotifications];
+        this.parsedNotifications = [...JSON.parse(newValue)];
+        this.resetUpdatedNotifications(prevParsedNotifications);
+        if (prevParsedNotifications.length < this.parsedNotifications.length) {
+            const latestNotification = this.parsedNotifications[0];
+            const actionText = latestNotification.link || latestNotification.action || "";
+            // don't announce link/action if user is tabbing because it is focused after announcement
+            this.announce(`${latestNotification.message} ${this.isTabbing ? "" : actionText}`);
+            if (!actionText) {
+                const newTimer = window.setTimeout(() => this.snackExpired(latestNotification.id), 6000);
+                this.timers = Object.assign({ [latestNotification.id]: newTimer }, this.timers);
+            }
+            else if (this.isTabbing) {
+                this.focusOnDismiss = document.activeElement ? document.activeElement : null;
+                this.stopTimer(latestNotification);
+                // allow snack to render before focusing
+                window.requestAnimationFrame(() => {
+                    const actionEl = this.el.shadowRoot.querySelector(`#action-${latestNotification.id}`);
+                    actionEl.focus();
+                });
+            }
+        }
+    }
+    resetUpdatedNotifications(prevNotifications) {
+        let updatedNotifications = [];
+        prevNotifications.forEach((prevNotification) => {
+            this.parsedNotifications.forEach((newNotification) => {
+                if (newNotification.id == prevNotification.id && newNotification.message != prevNotification.message) {
+                    updatedNotifications.push(newNotification);
+                }
+            });
+        });
+        updatedNotifications.forEach((updatedNotification) => {
+            const notifEl = this.el.shadowRoot.querySelector(`#snack-${updatedNotification.id}`);
+            if (notifEl) {
+                notifEl.classList.remove("grow");
+                window.requestAnimationFrame(() => notifEl.classList.add("grow"));
+            }
+            this.stopTimer(updatedNotification);
+            const actionText = updatedNotification.link || updatedNotification.action;
+            if (actionText) {
+                this.announce(`${updatedNotification.message} ${this.isTabbing ? "" : actionText}`);
+            }
+            else {
+                this.announce(updatedNotification.message);
+                const newTimer = window.setTimeout(() => this.snackExpired(updatedNotification.id), 6000);
+                this.timers = Object.assign({ [updatedNotification.id]: newTimer }, this.timers);
+            }
+        });
+    }
+    checkForTabbing(ev) {
+        if (ev.key === "Tab") {
+            this.isTabbing = true;
+        }
+    }
+    // Workaround for screenreader's triggering click event on "enter"
+    // This is why we manually handle this.isTabbing instead of listening to wmUserIsTabbing
+    handleMouse() {
+        this.isTabbing = false;
+    }
+    snackDismissed(notification) {
+        this.endSnack(notification);
+        // Focus should only be returned if it was moved in the first place, i.e., there was a link/action and the user was tabbing. Otherwise, for a mouse user, the user's focus would jump back to the triggering element.
+        if ((notification.link || notification.action) && this.isTabbing && this.focusOnDismiss) {
+            this.focusOnDismiss.focus();
+            this.focusOnDismiss = null;
+        }
+    }
+    //Remove snack from notification list once timer runs out
+    snackExpired(expiredID) {
+        const expiredNotification = this.parsedNotifications.find((n) => n.id == expiredID);
+        if (expiredNotification) {
+            this.endSnack(expiredNotification);
+        }
+    }
+    endSnack(notification) {
+        //App listens for wmSnackbarSnackFinished event and deletes the emitted notification.
+        this.stopTimer(notification);
+        const notifEl = this.el.shadowRoot.querySelector(`#snack-${notification.id}`);
+        notifEl.classList.add("shrink");
+        setTimeout(() => {
+            // wait for animation to complete, then emit event for removal
+            this.wmSnackbarSnackFinished.emit({
+                id: notification.id,
+                message: notification.message,
+                link: notification.link,
+                newWindow: notification.newWindow,
+                action: notification.action,
+            });
+        }, 250);
+    }
+    snackLinkClicked(notification) {
+        //App listens for wmSnackbarActionTriggered event, deletes emitted notification, and takes over focus.
+        this.stopTimer(notification);
+        this.wmSnackbarActionTriggered.emit({
+            id: notification.id,
+            message: notification.message,
+            link: notification.link,
+            newWindow: notification.newWindow,
+            action: notification.action,
+        });
+    }
+    //Delete the timer corresponding to the dismissed notification
+    stopTimer(notification) {
+        if (this.timers[notification.id]) {
+            clearTimeout(this.timers[notification.id]);
+            delete this.timers[notification.id];
+        }
+    }
+    announce(message) {
+        if (this.liveRegionEl.textContent === message) {
+            message += "\u00A0";
+        }
+        this.announcement = message;
+    }
+    renderSnackbars() {
+        return this.parsedNotifications.map((notification) => (h("div", { class: "wm-snack-wrapper", key: `snack-${notification.id}` }, h("div", { id: `snack-${notification.id}`, class: "wm-snackbar active neutral" }, h("div", { class: "sr-only", tabindex: notification.link || notification.action ? 0 : -1, onFocus: () => (notification.link || notification.action) && this.snackDismissed(notification) }), h("div", { class: "content-wrapper" }, h("div", { class: "msg-wrapper" }, h("span", { class: "msg" }, notification.message), notification.link && (h("a", { role: "link", id: `action-${notification.id}`, class: `link ${notification.newWindow ? "new-window" : ""}`, "aria-label": `${notification.link}${notification.newWindow ? " " + globalMessages.newWindow : ""}`, tabindex: 0, onClick: () => {
+                this.snackLinkClicked(notification);
+            }, onKeyDown: (ev) => ev.key === "Enter" && this.snackLinkClicked(notification) }, h("span", { "aria-hidden": "true" }, notification.link), notification.newWindow && h("div", { class: "svg-icon svg-open-in-new" }))), (!notification.link && notification.action) && (h("button", { id: `action-${notification.id}`, class: "link", onClick: () => this.snackLinkClicked(notification), onKeyDown: (ev) => ev.key === "Enter" && this.snackLinkClicked(notification) }, notification.action))), h("button", { id: `close-button-${notification.id}`, "aria-label": this.closeSnackMessage, class: "closesnack", tabindex: notification.link || notification.action ? 0 : -1, onClick: () => this.snackDismissed(notification), onMouseEnter: (ev) => showTooltip("bottom", ev.target, globalMessages.close), onMouseLeave: () => hideTooltip(), onFocus: (ev) => this.isTabbing && showTooltip("bottom", ev.target, globalMessages.close), onBlur: () => hideTooltip() }, h("div", { class: "svg-icon svg-close" }))), h("div", { class: "sr-only", tabindex: notification.link || notification.action ? 0 : -1, onFocus: () => (notification.link || notification.action) && this.snackDismissed(notification) })))));
+    }
+    render() {
+        return (h(Host, { key: '0e70d242a282e93aa784082ad24b2d46a7360b8e' }, h("div", { key: 'c18bb81ad201151cd17bf0cbd6a4ed905ed05704', ref: (el) => (this.snackAreaEl = el), class: {
+                "list-wrapper": true,
+                "user-is-tabbing": this.isTabbing,
+                empty: this.parsedNotifications.length == 0,
+            } }, this.renderSnackbars()), h("div", { key: '015af84cc94a71126be63ed28f015db03f7bad05', class: "sr-only", "aria-live": "polite", "aria-atomic": "false", id: `wm-live-region-${this.uid}`, ref: (el) => (this.liveRegionEl = el) }, this.announcement)));
+    }
+    static get is() { return "wm-snackbar"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-snackbar.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-snackbar.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "notifications": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "JSON-encoded array of notification objects to display. Each object must\ninclude `id` (string) and `message` (string). Optional fields: `link` (string, renders\na navigation anchor), `action` (string, renders a button), `newWindow` (boolean, adds an\n\"opens in new window\" indicator to the link). Always pass as `JSON.stringify(array)` \u2014\npassing an array directly causes a \"[object Object] is not valid JSON\" error."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "notifications",
+                "reflect": true,
+                "defaultValue": "\"[]\""
+            }
+        };
+    }
+    static get states() {
+        return {
+            "isTabbing": {},
+            "announcement": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "wmSnackbarSnackFinished",
+                "name": "wmSnackbarSnackFinished",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when a notification should be removed \u2014 after the 6-second\nauto-dismiss timer expires or when the user clicks the close button. The host application\nshould remove the matching notification from its array. The timer is disabled for\nnotifications with a `link` or `action`."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ id: string, message: string, link?: string, newWindow?: boolean, action?: string }}"
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "Object",
+                    "resolved": "Object",
+                    "references": {
+                        "Object": {
+                            "location": "global",
+                            "id": "global::Object"
+                        }
+                    }
+                }
+            }, {
+                "method": "wmSnackbarActionTriggered",
+                "name": "wmSnackbarActionTriggered",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks the `link` anchor or `action` button. The host\napplication should remove the notification and navigate (for links) or execute the action\n(for buttons)."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ id: string, message: string, link?: string, newWindow?: boolean, action?: string }}"
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "Object",
+                    "resolved": "Object",
+                    "references": {
+                        "Object": {
+                            "location": "global",
+                            "id": "global::Object"
+                        }
+                    }
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "notifications",
+                "methodName": "updateSnacks"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "keydown",
+                "method": "checkForTabbing",
+                "target": "document",
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "mouseover",
+                "method": "handleMouse",
+                "target": "document",
+                "capture": false,
+                "passive": true
+            }];
+    }
+}