@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/collection/components/wm-tabs/wm-tab-list/wm-tab-list.js

@@ -0,0 +1,461 @@
+import { h, Host } from "@stencil/core";
+import { debounce, intl } from "../../../global/functions";
+/**
+ * Tab list container that manages a group of wm-tab-item children and their associated
+ * wm-tab-panel elements. Handles keyboard navigation, ARIA wiring between tabs and panels,
+ * horizontal scroll with arrow buttons on overflow, and optional dark theme.
+ *
+ * @category Navigation
+ * @displayName Tabs
+ *
+ * @slot - One or more wm-tab-item elements.
+ *
+ * @keyboardInteraction
+ * - **Arrow Left / Arrow Right**: Cycles focus to the previous/next tab item; wraps at both ends.
+ * - **Arrow Down**: Moves focus to the content area of the active tab panel.
+ * - **Enter / Space**: Activates the focused tab and shows its panel.
+ * - **Tab**: Moves focus from the selected tab to the first focusable element inside the
+ *   active panel.
+ * - **Shift+Tab**: Moves focus back to the selected tab item from within the panel.
+ *
+ * @accessibility
+ * - Sets `aria-controls` on each wm-tab-item link pointing to its associated wm-tab-panel.
+ * - Sets `aria-labelledby` on each wm-tab-panel pointing back to its wm-tab-item link.
+ * - ARIA attributes are updated dynamically when tab content is conditionally rendered in a
+ *   single shared panel.
+ *
+ * @usageNotes
+ * - Set the container's width to 100% in most cases.
+ * - Two usage patterns:
+ *   1. **Discrete panels** — each wm-tab-item has a paired wm-tab-panel with the same `tab-id`.
+ *   2. **Single panel** — one wm-tab-panel; content is rendered conditionally based on the
+ *      selected tab; ARIA attributes are updated automatically.
+ * - At least one wm-tab-panel is required — wm-tab-list only renders the tab strip, not the
+ *   content area. A wm-tab-item's `tab-id` must exactly match its wm-tab-panel's `tab-id`
+ *   (or the shared panel's `tab-id`, for the single-panel pattern). A missing or mismatched
+ *   `tab-id` fails silently: no console warning, the tab's `aria-controls`/`href` never get
+ *   set, and its panel never activates.
+ * - Listen to `wmTabSelected` on wm-tab-item (or on the wm-tab-list, as the event bubbles) and
+ *   update `selected-tab` to switch the active tab.
+ * - Use `selected-tab` to control which tab is initially active by its `tab-id`.
+ *
+ * @example {html} Basic tabs (discrete panels)
+ * <wm-tab-list>
+ *   <wm-tab-item tab-id="overview">Overview</wm-tab-item>
+ *   <wm-tab-item tab-id="details">Details</wm-tab-item>
+ *   <wm-tab-item tab-id="history">History</wm-tab-item>
+ * </wm-tab-list>
+ * <wm-tab-panel tab-id="overview"><p>Overview content</p></wm-tab-panel>
+ * <wm-tab-panel tab-id="details"><p>Details content</p></wm-tab-panel>
+ * <wm-tab-panel tab-id="history"><p>History content</p></wm-tab-panel>
+ *
+ * @example {react} Basic tabs (discrete panels)
+ * // wmTabSelected fires when a tab is clicked or activated via keyboard.
+ * // event.detail is { tabId: string } -- the tab-id of the newly selected tab.
+ * const [selectedTab, setSelectedTab] = useState("overview");
+ *
+ * <WmTabList selectedTab={selectedTab} onWmTabSelected={(e) => setSelectedTab(e.detail.tabId)}>
+ *   <WmTabItem tabId="overview">Overview</WmTabItem>
+ *   <WmTabItem tabId="details">Details</WmTabItem>
+ *   <WmTabItem tabId="history">History</WmTabItem>
+ * </WmTabList>
+ * <WmTabPanel tabId="overview"><p>Overview content</p></WmTabPanel>
+ * <WmTabPanel tabId="details"><p>Details content</p></WmTabPanel>
+ * <WmTabPanel tabId="history"><p>History content</p></WmTabPanel>
+ *
+ * @example {html} Single shared panel (content rendered conditionally)
+ * <wm-tab-list custom-background="dark">
+ *   <wm-tab-item tab-id="summary">Summary</wm-tab-item>
+ *   <wm-tab-item tab-id="activity">Activity</wm-tab-item>
+ * </wm-tab-list>
+ * <wm-tab-panel tab-id="summary">
+ *   <!-- app renders content here based on the active tab -->
+ * </wm-tab-panel>
+ *
+ * @example {react} Single shared panel (content rendered conditionally)
+ * // One wm-tab-panel shared by all tabs -- ARIA attributes update automatically.
+ * // Render content conditionally based on selectedTab.
+ * const [selectedTab, setSelectedTab] = useState("summary");
+ *
+ * <WmTabList
+ *   customBackground="dark"
+ *   selectedTab={selectedTab}
+ *   onWmTabSelected={(e) => setSelectedTab(e.detail.tabId)}
+ * >
+ *   <WmTabItem tabId="summary">Summary</WmTabItem>
+ *   <WmTabItem tabId="activity">Activity</WmTabItem>
+ * </WmTabList>
+ * <WmTabPanel tabId="summary">
+ *   {selectedTab === "summary" && <p>Summary content</p>}
+ *   {selectedTab === "activity" && <p>Activity content</p>}
+ * </WmTabPanel>
+ *
+ * @requiredSetup
+ * - Handle `wmTabSelected` on the list -- it is declared on wm-tab-item and bubbles -- and write
+ *   `event.detail.tabId` to `selected-tab`.
+ * - Slot a wm-tab-item per tab, and render a wm-tab-panel for each one as its content container.
+ * - Give each wm-tab-item `tab-id` the same value as its wm-tab-panel `tab-id`. A mismatch fails
+ *   silently: the tab highlights and no panel appears.
+ *
+ */
+export class TabList {
+    constructor() {
+        this.debouncedUpdateContainerState = debounce(() => {
+            this.updateContainerFade();
+            this.updateArrowVisibility();
+        }, 16);
+        this.customBackground = undefined;
+        this.selectedTab = undefined;
+        this.announcement = "";
+        this.containerFadeLeft = false;
+        this.containerFadeRight = false;
+        this.scrollArrowsVisible = false;
+    }
+    get tabItems() {
+        return Array.from(this.el.querySelectorAll("wm-tab-item"));
+    }
+    get selectedTabItem() {
+        return this.tabItems.filter((t) => t.selected)[0];
+    }
+    getLinkEl(tab) {
+        return tab.shadowRoot.querySelector("a");
+    }
+    get panels() {
+        const allPanels = Array.from(document.querySelectorAll("wm-tab-panel"));
+        const tabIds = this.tabItems.map((t) => t.tabId);
+        return allPanels.filter((p) => tabIds.includes(p.tabId));
+    }
+    setSelected(id) {
+        this.tabItems.map((tab) => (tab.selected = tab.tabId === id));
+        const singlePanel = this.panels.length === 1 && this.tabItems.length > 1;
+        if (singlePanel) {
+            /**
+             * If the app conditionally renders content in one single tab panel rather than allocating the content to discrete panels, then the tab panels aria references needs to update whenever a new tab item is selected.
+             */
+            this.setAttributesOnPanel(this.panels[0], this.selectedTabItem);
+            this.panels[0].active = true;
+        }
+        else {
+            this.panels.map((panel) => (panel.active = panel.tabId === id));
+        }
+        this.handleTabFocused(this.selectedTabItem);
+    }
+    componentWillLoad() {
+        this.el.focus = () => {
+            // in addition to delegatesFocus, we need to highjack the focus method to send focus to the selected tab-item
+            this.selectedTabItem && this.selectedTabItem.focus({ preventScroll: true });
+        };
+    }
+    componentDidLoad() {
+        const selectedTab = this.selectedTab || this.tabItems[0].tabId;
+        this.setSelected(selectedTab);
+        this.updateArrowVisibility();
+        this.tabContainerEl.addEventListener("scroll", this.debouncedUpdateContainerState);
+        const resizeObserver = new ResizeObserver(() => this.debouncedUpdateContainerState());
+        resizeObserver.observe(this.el);
+        requestAnimationFrame(() => {
+            // Wait for layout to complete before measuring and scrolling initial tab into view
+            this.handleTabFocused(this.selectedTabItem);
+        });
+    }
+    tabItemLoaded(ev) {
+        this.setAriaOnPanelAndTab(ev.target);
+    }
+    wmTabFocused(ev) {
+        this.handleTabFocused(ev.detail.tabItem);
+    }
+    setAriaOnPanelAndTab(tab) {
+        const panel = this.panels.find((p) => p.tabId === tab.tabId);
+        // If there's no panel, check for case where content is conditionally rendered in one panel, in which case attributes on all tabs should point to this single panel.
+        if (!panel) {
+            if (this.panels.length === 1) {
+                this.setAttributesOnTab(tab, this.panels[0]);
+            }
+        }
+        else {
+            // Otherwise, set attributes on each tab item that loads and its associated panel
+            this.setAttributesOnPanel(panel, tab);
+            this.setAttributesOnTab(tab, panel);
+        }
+    }
+    setAttributesOnTab(tab, panel) {
+        const link = this.getLinkEl(tab);
+        if (link) {
+            link.setAttribute("href", `#${panel.id}`);
+        }
+    }
+    removeAttributesOnTab(tab) {
+        const link = this.getLinkEl(tab);
+        if (link) {
+            link.removeAttribute("href");
+        }
+    }
+    setAttributesOnPanel(panel, tab) {
+        const link = this.getLinkEl(tab);
+        if (link) {
+            panel.setAttribute("aria-labelledby", link.id);
+            panel.setAttribute("tab-id", tab.tabId);
+        }
+    }
+    handleKeydown(ev) {
+        const key = ev.detail.key;
+        let index = this.tabItems.indexOf(ev.detail.tabItem);
+        // focusing panel on down arrow
+        if (key === "ArrowDown") {
+            const activePanel = this.panels.filter((p) => p.active)[0];
+            activePanel && activePanel.focus();
+        }
+        else if (key === "ArrowLeft" || key === "ArrowRight") {
+            // focusing prev/next tab item on right/left arrow
+            if (key) {
+                index = key === "ArrowLeft" ? index - 1 : index + 1;
+            }
+            if (index < 0) {
+                index = this.tabItems.length - 1;
+            }
+            else if (index === this.tabItems.length) {
+                index = 0;
+            }
+            const tabToFocus = this.tabItems[index];
+            this.getLinkEl(tabToFocus).focus({ preventScroll: true });
+        }
+    }
+    handleTabFocused(tabItem, alignment = "auto") {
+        // Calculate and apply scroll position
+        const targetScrollLeft = this.calculateScrollPositionForTab(tabItem, alignment);
+        this.tabContainerEl.scrollTo({ left: targetScrollLeft, behavior: "smooth" });
+    }
+    calculateScrollPositionForTab(tabItem, alignment = "auto") {
+        const containerRect = this.tabContainerEl.getBoundingClientRect();
+        const containerScrollLeft = this.tabContainerEl.scrollLeft;
+        const tabRect = tabItem.getBoundingClientRect();
+        const tabLeft = containerScrollLeft + (tabRect.left - containerRect.left);
+        const tabRight = tabLeft + tabRect.width;
+        // Explicit alignment
+        if (alignment === "left") {
+            return tabLeft; // Snap to left edge
+        }
+        if (alignment === "right") {
+            return Math.max(0, tabRight - containerRect.width); // Snap to right edge
+        }
+        // Auto alignment
+        const firstTab = this.tabItems[0];
+        const lastTab = this.tabItems[this.tabItems.length - 1];
+        if (tabItem === firstTab) {
+            return 0;
+        }
+        if (tabItem === lastTab) {
+            return Math.max(0, this.tabContainerEl.scrollWidth - containerRect.width);
+        }
+        if (tabLeft < containerScrollLeft) {
+            return tabLeft; // Left edge cut off, align left
+        }
+        if (tabRight > containerScrollLeft + containerRect.width) {
+            return tabRight - containerRect.width; // Right edge cut off, align right
+        }
+        return containerScrollLeft; // Fully visible, no scroll needed
+    }
+    updateContainerFade() {
+        const tolerance = 1; // 1px tolerance for floating-point precision
+        // Check if there's content scrolled out of view on each side
+        let shouldFadeLeft = this.tabContainerEl.scrollLeft > tolerance;
+        let shouldFadeRight = this.tabContainerEl.scrollLeft + this.tabContainerEl.clientWidth < this.tabContainerEl.scrollWidth - tolerance;
+        const focusedTab = this.tabItems.find((tab) => tab.matches(":focus-within"));
+        if (focusedTab) {
+            const containerRect = this.tabContainerEl.getBoundingClientRect();
+            const tabRect = focusedTab.getBoundingClientRect();
+            const isAtOrOverlappingLeft = tabRect.left <= containerRect.left + tolerance;
+            const isAtOrOverlappingRight = tabRect.right >= containerRect.right - tolerance;
+            if (isAtOrOverlappingLeft) {
+                shouldFadeLeft = false; // Don't fade left if focused tab is at/beyond left edge
+            }
+            if (isAtOrOverlappingRight) {
+                shouldFadeRight = false; // Don't fade right if focused tab is at/beyond right edge
+            }
+        }
+        this.containerFadeLeft = shouldFadeLeft;
+        this.containerFadeRight = shouldFadeRight;
+    }
+    updateArrowVisibility() {
+        const leftArrowEl = this.el.shadowRoot.querySelector(".left-arrow");
+        const rightArrowEl = this.el.shadowRoot.querySelector(".right-arrow");
+        const isScrollable = this.tabContainerEl.scrollWidth > this.tabContainerEl.clientWidth;
+        this.scrollArrowsVisible = isScrollable;
+        requestAnimationFrame(() => {
+            // Let arrows render before checking if they should be disabled
+            if (this.scrollArrowsVisible) {
+                const tolerance = 1; // 1px tolerance for floating-point precision
+                const canScrollLeft = this.tabContainerEl.scrollLeft > tolerance;
+                const canScrollRight = this.tabContainerEl.scrollLeft + this.tabContainerEl.clientWidth <
+                    this.tabContainerEl.scrollWidth - tolerance;
+                leftArrowEl.classList.toggle("disabled", !canScrollLeft);
+                rightArrowEl.classList.toggle("disabled", !canScrollRight);
+            }
+        });
+    }
+    handleLeftArrowClick(ev) {
+        const buttonEl = ev.target;
+        if (buttonEl.classList.contains("disabled")) {
+            // If the arrow is disabled, take no action and announce reason
+            this.announce(intl.formatMessage({
+                id: "tabs.cannotScrollLeft",
+                defaultMessage: "No more tabs to the left",
+                description: "Announcement for button scrolling tab group.",
+            }));
+            return;
+        }
+        // Find the first tab that's partially or completely obscured on the left
+        const containerRect = this.tabContainerEl.getBoundingClientRect();
+        const containerLeft = containerRect.left;
+        let tabToFocus = null;
+        const reversedTabItems = this.tabItems.reverse();
+        reversedTabItems.forEach((tab) => {
+            if (!tabToFocus) {
+                const tabRect = tab.getBoundingClientRect();
+                if (tabRect.left < containerLeft - 1) {
+                    tabToFocus = tab;
+                }
+            }
+        });
+        if (tabToFocus) {
+            this.handleTabFocused(tabToFocus, "right"); // Snap to right edge for page-scroll behavior
+        }
+    }
+    handleRightArrowClick(ev) {
+        const buttonEl = ev.target;
+        if (buttonEl.classList.contains("disabled")) {
+            this.announce(intl.formatMessage({
+                id: "tabs.cannotScrollRight",
+                defaultMessage: "No more tabs to the right",
+                description: "Announcement for button scrolling tab group.",
+            }));
+            return;
+        }
+        // Find the first tab that's partially or completely obscured on the right
+        const containerRect = this.tabContainerEl.getBoundingClientRect();
+        const containerRight = containerRect.right;
+        let tabToFocus = null;
+        this.tabItems.forEach((tab) => {
+            if (!tabToFocus) {
+                const tabRect = tab.getBoundingClientRect();
+                if (tabRect.right > containerRight + 1) {
+                    tabToFocus = tab;
+                }
+            }
+        });
+        if (tabToFocus) {
+            this.handleTabFocused(tabToFocus, "left"); // Snap to left edge for page-scroll behavior
+        }
+    }
+    announce(message) {
+        // \u00A0 is a non-breaking space character, which causes the message to be read as a new one
+        if (this.liveRegionEl.textContent === message) {
+            message += "\u00A0";
+        }
+        this.announcement = message;
+    }
+    render() {
+        return (h(Host, { key: 'e5e70580b7b292940ae6f78b1a7e11b10c094816' }, h("div", { key: 'd4522bc80583555f1a30c75e75ed83746aaebf52', class: "component-wrapper" }, h("wm-button", { key: '302eefe25f531312166fc63be510e48153620bc7', class: `left-arrow ${this.scrollArrowsVisible ? "visible" : ""}`, "aria-controls": "tablist", customBackground: this.customBackground, buttonType: "navigational", icon: "#previous", tooltip: intl.formatMessage({
+                id: "tabs.showPreviousTabs",
+                defaultMessage: "Show previous tabs",
+                description: "Tooltip for button scrolling tab group.",
+            }), onClick: (ev) => this.handleLeftArrowClick(ev) }), h("ul", { key: '0a8a050783bb051d40fa837a4715662b2d1d7455', id: "tablist", ref: (el) => (this.tabContainerEl = el), class: `tabcontainer ${this.customBackground || ""} ${this.containerFadeLeft ? "fade-left" : ""} ${this.containerFadeRight ? "fade-right" : ""}`, role: "tablist", tabIndex: -1 }, h("slot", { key: '02a0d8d6d5674b4512287987944d21a432357ac7' })), h("wm-button", { key: 'c96ff969e596c0ba93f90ab4dacb9bcd95587e36', class: `right-arrow ${this.scrollArrowsVisible ? "visible" : ""}`, "aria-controls": "tablist", customBackground: this.customBackground, buttonType: "navigational", icon: "#next", tooltip: intl.formatMessage({
+                id: "tabs.showNextTabs",
+                defaultMessage: "Show next tabs",
+                description: "Tooltip for button scrolling tab group.",
+            }), onClick: (ev) => this.handleRightArrowClick(ev) }), h("span", { key: '4925ff672c42cbe5c69a5ad33ee4812c93cf2f00', "aria-live": "assertive", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement))));
+    }
+    static get is() { return "wm-tab-list"; }
+    static get encapsulation() { return "shadow"; }
+    static get delegatesFocus() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-tab-list.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-tab-list.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "customBackground": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"dark\" | \"\"",
+                    "resolved": "\"\" | \"dark\" | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Sets the visual theme. Pass `\"dark\"` for the dark theme; omit for the\ndefault light theme."
+                        }],
+                    "text": ""
+                },
+                "attribute": "custom-background",
+                "reflect": false
+            },
+            "selectedTab": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "The `tab-id` of the currently active tab. Update this prop in response to\n`wmTabSelected` to switch tabs. Defaults to the first tab if not set."
+                        }],
+                    "text": ""
+                },
+                "attribute": "selected-tab",
+                "reflect": false
+            }
+        };
+    }
+    static get states() {
+        return {
+            "announcement": {},
+            "containerFadeLeft": {},
+            "containerFadeRight": {},
+            "scrollArrowsVisible": {}
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "selectedTab",
+                "methodName": "setSelected"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "tabItemLoaded",
+                "method": "tabItemLoaded",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "wmIntTabFocused",
+                "method": "wmTabFocused",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "keydownOnTabItem",
+                "method": "handleKeydown",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }];
+    }
+}