@swisspost/design-system-components 10.0.0-next.55 → 10.0.0-next.57

package/dist/collection/components/post-tabs/post-tabs.js

@@ -1,52 +1,172 @@
-import { h, Host } from "@stencil/core";
+import { h, Host, } from "@stencil/core";
 import { version } from "../../../../package";
-import { fadeIn, fadeOut } from "../../animations/index";
-import { componentOnReady } from "../../utils/index";
+import { fade } from "../../animations/index";
+import { componentOnReady, checkRequiredAndType } from "../../utils/index";
 /**
- * @slot tabs - Slot for placing tab headers. Each tab header should be a <post-tab-header> element.
- * @slot default - Slot for placing tab panels. Each tab panel should be a <post-tab-panel> element.
- * @part tabs - The container element that holds the set of tabs.
- * @part content - The container element that displays the content of the currently active tab.
+ * @slot default - Slot for placing tab items. Each tab item should be a <post-tab-item> element.
+ * @slot panels - Slot for placing tab panels. Each tab panel should be a <post-tab-panel> element.
+ * @part post-tabs - The container element that holds the set of tabs.
+ * @part post-tabs-content - The container element that displays the content of the currently active tab. Only available in panels mode.
  */
 export class PostTabs {
     constructor() {
         this.isLoaded = false;
+        this.isNavigationMode = false;
         /**
          * When set to true, this property allows the tabs container to span the
+         * Changing this value after initialization has no effect.
          * full width of the screen, from edge to edge.
          */
         this.fullWidth = false;
     }
     get tabs() {
-        return Array.from(this.host.querySelectorAll('post-tab-header')).filter(tab => tab.closest('post-tabs') === this.host);
+        return Array.from(this.host.querySelectorAll('post-tab-item')).filter(tab => tab.closest('post-tabs') === this.host);
+    }
+    get panels() {
+        return Array.from(this.host.querySelectorAll('post-tab-panel')).filter(panel => panel.closest('post-tabs') === this.host);
+    }
+    validateLabel() {
+        if (this.isNavigationMode) {
+            checkRequiredAndType(this, 'label', 'string');
+        }
+    }
+    componentWillRender() {
+        this.detectMode();
     }
     componentDidLoad() {
         this.moveMisplacedTabs();
+        this.moveMisplacedPanels();
         this.enableTabs();
-        const initiallyActivePanel = this.activePanel || this.tabs[0]?.panel;
-        void this.show(initiallyActivePanel);
-        this.isLoaded = true;
+        this.setupContentObserver();
+        this.validateLabel();
+        if (this.isNavigationMode) {
+            const activeTab = this.findActiveNavigationTab();
+            if (activeTab) {
+                this.activateTab(activeTab);
+            }
+        }
+        else {
+            const tabToActivate = this.activeTab || this.tabs[0]?.name;
+            if (tabToActivate) {
+                void this.show(tabToActivate);
+            }
+        }
+    }
+    disconnectedCallback() {
+        if (this.showing) {
+            this.showing.cancel();
+            this.showing = null;
+        }
+        if (this.hiding) {
+            this.hiding.cancel();
+            this.hiding = null;
+        }
+        if (this.contentObserver) {
+            this.contentObserver.disconnect();
+        }
+    }
+    setupContentObserver() {
+        const config = {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ['data-navigation-mode', 'aria-current'],
+        };
+        this.contentObserver = new MutationObserver(this.handleContentChange.bind(this));
+        this.contentObserver.observe(this.host, config);
+    }
+    handleContentChange(mutations) {
+        const shouldRedetect = this.shouldRedetectMode(mutations);
+        const ariaCurrentChanged = this.hasAriaCurrentChanged(mutations);
+        if (ariaCurrentChanged && this.isNavigationMode) {
+            this.updateActiveNavigationTab();
+        }
+        if (shouldRedetect) {
+            this.handleModeChange();
+        }
+    }
+    shouldRedetectMode(mutations) {
+        return mutations.some(mutation => {
+            if (mutation.type === 'childList') {
+                return mutation.addedNodes.length > 0 || mutation.removedNodes.length > 0;
+            }
+            if (mutation.type === 'attributes' && mutation.attributeName === 'data-navigation-mode') {
+                return true;
+            }
+            return false;
+        });
+    }
+    hasAriaCurrentChanged(mutations) {
+        return mutations.some(mutation => mutation.type === 'attributes' && mutation.attributeName === 'aria-current');
+    }
+    updateActiveNavigationTab() {
+        const activeTab = this.findActiveNavigationTab();
+        if (activeTab && activeTab !== this.currentActiveTab) {
+            this.activateTab(activeTab);
+        }
+    }
+    handleModeChange() {
+        const previousMode = this.isNavigationMode;
+        this.detectMode();
+        if (previousMode !== this.isNavigationMode) {
+            this.enableTabs();
+            this.initializeActiveTab();
+        }
+    }
+    initializeActiveTab() {
+        if (this.isNavigationMode) {
+            const activeTab = this.findActiveNavigationTab();
+            if (activeTab) {
+                this.activateTab(activeTab);
+            }
+        }
+        else {
+            const tabToActivate = this.activeTab || this.tabs[0]?.name;
+            if (tabToActivate) {
+                void this.show(tabToActivate);
+            }
+        }
+    }
+    detectMode() {
+        // Check for navigation mode by looking for anchor elements in tabs
+        // This works even before post-tab-item sets data-navigation-mode attribute
+        const hasNavigationTabs = this.tabs.some(tab => {
+            const hasAnchor = tab.querySelector('a') !== null;
+            const navModeAttr = tab.getAttribute('data-navigation-mode') === 'true';
+            return hasAnchor || navModeAttr;
+        });
+        const hasPanels = this.panels.length > 0;
+        if (hasNavigationTabs && hasPanels) {
+            throw new Error('PostTabs: Mixed mode detected. Cannot use both navigation mode (anchor elements) and panel mode (post-tab-panel elements) at the same time.');
+        }
+        this.isNavigationMode = hasNavigationTabs;
+    }
+    findActiveNavigationTab() {
+        return (this.tabs.find(tab => {
+            const anchor = tab.querySelector('a[aria-current="page"]');
+            return anchor !== null;
+        }) || null);
     }
     /**
      * Shows the panel with the given name and selects its associated tab.
      * Any other panel that was previously shown becomes hidden and its associated tab is unselected.
      */
-    async show(panelName) {
+    async show(tabName) {
         // do nothing if the tab is already active
-        if (panelName === this.activeTab?.panel) {
+        if (tabName === this.currentActiveTab?.name) {
             return;
         }
-        const previousTab = this.activeTab;
-        const newTab = this.host.querySelector(`post-tab-header[panel=${panelName}]`);
+        const previousTab = this.currentActiveTab;
+        const newTab = this.host.querySelector(`post-tab-item[name=${tabName}]`);
         this.activateTab(newTab);
         // if a panel is currently being displayed, remove it from the view and complete the associated animation
         if (this.showing) {
-            this.showing.effect['target'].style.display = 'none';
             this.showing.finish();
+            this.showing = null;
         }
         // hide the currently visible panel only if no other animation is running
         if (previousTab && !this.showing && !this.hiding)
-            this.hidePanel(previousTab.panel);
+            this.hidePanel(previousTab.name);
         // wait for any hiding animation to complete before showing the selected tab
         if (this.hiding)
             await this.hiding.finished;
@@ -55,15 +175,25 @@ export class PostTabs {
         if (this.showing)
             await this.showing.finished;
         if (this.isLoaded)
-            this.postChange.emit(this.activeTab.panel);
+            this.postChange.emit(this.currentActiveTab.name);
     }
     moveMisplacedTabs() {
         if (!this.tabs)
             return;
         this.tabs.forEach(tab => {
-            if (tab.getAttribute('slot') === 'tabs')
-                return;
-            tab.setAttribute('slot', 'tabs');
+            // Tab items should go in the default slot, so remove any slot attribute
+            if (tab.getAttribute('slot')) {
+                tab.removeAttribute('slot');
+            }
+        });
+    }
+    moveMisplacedPanels() {
+        if (!this.panels)
+            return;
+        this.panels.forEach(panel => {
+            if (panel.getAttribute('slot') !== 'panels') {
+                panel.setAttribute('slot', 'panels');
+            }
         });
     }
     enableTabs() {
@@ -71,19 +201,25 @@ export class PostTabs {
             return;
         this.tabs.forEach(async (tab) => {
             await componentOnReady(tab);
-            // if the tab has an "aria-controls" attribute it was already linked to its panel: do nothing
+            // In navigation mode, navigation is handled by the consumer's routing
+            if (this.isNavigationMode) {
+                return;
+            }
+            // Panel mode: set up ARIA relationships and event handlers
             if (tab.getAttribute('aria-controls'))
                 return;
-            const tabPanel = this.getPanel(tab.panel);
-            tab.setAttribute('aria-controls', tabPanel.id);
-            tabPanel.setAttribute('aria-labelledby', tab.id);
+            const tabPanel = this.getPanel(tab.name);
+            if (tabPanel) {
+                tab.setAttribute('aria-controls', tabPanel.id);
+                tabPanel.setAttribute('aria-labelledby', tab.id);
+            }
             tab.addEventListener('click', () => {
-                void this.show(tab.panel);
+                void this.show(tab.name);
             });
             tab.addEventListener('keydown', (e) => {
                 if (e.key === 'Enter' || e.key === ' ') {
                     e.preventDefault();
-                    void this.show(tab.panel);
+                    void this.show(tab.name);
                 }
             });
             tab.addEventListener('keydown', (e) => {
@@ -92,44 +228,51 @@ export class PostTabs {
             });
         });
         // if the currently active tab was removed from the DOM then select the first one
-        if (this.activeTab && !this.activeTab.isConnected) {
-            void this.show(this.tabs[0]?.panel);
+        if (this.currentActiveTab && !this.currentActiveTab.isConnected) {
+            void this.show(this.tabs[0]?.name);
         }
     }
     activateTab(tab) {
-        if (this.activeTab) {
-            this.activeTab.setAttribute('aria-selected', 'false');
-            this.activeTab.setAttribute('tabindex', '-1');
-            this.activeTab.classList.remove('active');
+        // Deactivate previous tab
+        if (this.currentActiveTab) {
+            this.currentActiveTab.classList.remove('active');
+            if (!this.isNavigationMode) {
+                this.currentActiveTab.setAttribute('aria-selected', 'false');
+                this.currentActiveTab.setAttribute('tabindex', '-1');
+            }
         }
-        tab.setAttribute('aria-selected', 'true');
-        tab.setAttribute('tabindex', '0');
         tab.classList.add('active');
-        this.activeTab = tab;
+        if (!this.isNavigationMode) {
+            tab.setAttribute('aria-selected', 'true');
+            tab.setAttribute('tabindex', '0');
+        }
+        this.currentActiveTab = tab;
     }
     hidePanel(panelName) {
         const previousPanel = this.getPanel(panelName);
         if (!previousPanel)
             return;
-        this.hiding = fadeOut(previousPanel);
+        this.hiding = fade(previousPanel, 'out');
         this.hiding.onfinish = () => {
             previousPanel.style.display = 'none';
             this.hiding = null;
         };
     }
     showSelectedPanel() {
-        const panel = this.getPanel(this.activeTab.panel);
+        const panel = this.getPanel(this.currentActiveTab.name);
+        if (!panel)
+            return;
         panel.style.display = 'block';
         // prevent the initially selected panel from fading in
         if (!this.isLoaded)
             return;
-        this.showing = fadeIn(panel);
+        this.showing = fade(panel, 'in');
         this.showing.onfinish = () => {
             this.showing = null;
         };
     }
     getPanel(name) {
-        return this.host.querySelector(`post-tab-panel[name=${name}]`);
+        return this.host.querySelector(`post-tab-panel[for=${name}]`);
     }
     navigateTabs(tab, key) {
         const activeTabIndex = Array.from(this.tabs).indexOf(tab);
@@ -143,9 +286,14 @@ export class PostTabs {
         if (!nextTab)
             return;
         nextTab.focus();
+        void this.show(nextTab.name);
     }
     render() {
-        return (h(Host, { key: 'f3534a3b05c379ce1cb311d4c5ea950c8eba87d0', "data-version": version }, h("div", { key: 'd812db6b2a895504fce8ac9dae2663821b9dd759', class: "tabs-wrapper", part: "tabs" }, h("div", { key: '9abd0ee00204a085ceaebce5e11fcff527273605', class: "tabs", role: "tablist" }, h("slot", { key: '89f09f443ca740dc9af66fedb1367cdb4885074d', name: "tabs", onSlotchange: () => this.enableTabs() }))), h("div", { key: '4a94a19fd67814482934bd31bb219470bea8dec6', class: "tab-content", part: "content" }, h("slot", { key: '44db446865edacb1b1c0fc20ef391adfa189e8cb', onSlotchange: () => this.moveMisplacedTabs() }))));
+        const TabsContainer = this.isNavigationMode ? 'nav' : 'div';
+        return (h(Host, { key: '89edc2a79734ee9cd60c9db0f01e2f05f2849071', "data-version": version }, h("div", { key: 'd85aa2320cef490831bf59117b54dc7c4edd9d65', class: "tabs-wrapper", part: "post-tabs" }, h(TabsContainer, { key: 'e4aa70db5e2d0f3391d8ebfaab6374c1966d6678', class: "tabs", role: this.isNavigationMode ? undefined : 'tablist', "aria-label": this.isNavigationMode ? this.label : undefined }, h("slot", { key: '7ab6f1e7bbe24ef642d5917b810b62e362ae2dc1', onSlotchange: () => {
+                this.moveMisplacedTabs();
+                this.enableTabs();
+            } }))), !this.isNavigationMode && (h("div", { key: '354eafcea40f6aa9bbb206a93bc2155eac725bb4', class: "tab-content", part: "post-tabs-content" }, h("slot", { key: 'a133b48cea08eade14a954933062380edf112523', name: "panels", onSlotchange: () => this.moveMisplacedPanels() })))));
     }
     static get is() { return "post-tabs"; }
     static get encapsulation() { return "shadow"; }
@@ -161,33 +309,27 @@ export class PostTabs {
     }
     static get properties() {
         return {
-            "activePanel": {
+            "activeTab": {
                 "type": "string",
-                "attribute": "active-panel",
                 "mutable": false,
                 "complexType": {
-                    "original": "HTMLPostTabPanelElement['name']",
+                    "original": "string",
                     "resolved": "string",
-                    "references": {
-                        "HTMLPostTabPanelElement": {
-                            "location": "global",
-                            "id": "global::HTMLPostTabPanelElement"
-                        }
-                    }
+                    "references": {}
                 },
                 "required": false,
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "The name of the panel that is initially shown.\nIf not specified, it defaults to the panel associated with the first tab.\n\n**Changing this value after initialization has no effect.**"
+                    "text": "The name of the tab in the panel mode that is initially active.\nChanging this value after initialization has no effect.\nIf not specified, defaults to the first tab."
                 },
                 "getter": false,
                 "setter": false,
-                "reflect": false
+                "reflect": false,
+                "attribute": "active-tab"
             },
             "fullWidth": {
                 "type": "boolean",
-                "attribute": "full-width",
                 "mutable": false,
                 "complexType": {
                     "original": "boolean",
@@ -198,15 +340,40 @@ export class PostTabs {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "When set to true, this property allows the tabs container to span the\nfull width of the screen, from edge to edge."
+                    "text": "When set to true, this property allows the tabs container to span the\nChanging this value after initialization has no effect.\nfull width of the screen, from edge to edge."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": true,
+                "attribute": "full-width",
                 "defaultValue": "false"
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "The accessible label for the tabs component in navigation mode."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "label"
             }
         };
     }
+    static get states() {
+        return {
+            "isNavigationMode": {}
+        };
+    }
     static get events() {
         return [{
                 "method": "postChange",
@@ -216,7 +383,7 @@ export class PostTabs {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "An event emitted after the active tab changes, when the fade in transition of its associated panel is finished.\nThe payload is the name of the newly shown panel."
+                    "text": "An event emitted after the active tab changes, when the fade in transition of its associated panel is finished.\nThe payload is the name of the newly active tab.\nOnly emitted in panel mode."
                 },
                 "complexType": {
                     "original": "string",
@@ -229,9 +396,9 @@ export class PostTabs {
         return {
             "show": {
                 "complexType": {
-                    "signature": "(panelName: string) => Promise<void>",
+                    "signature": "(tabName: string) => Promise<void>",
                     "parameters": [{
-                            "name": "panelName",
+                            "name": "tabName",
                             "type": "string",
                             "docs": ""
                         }],
@@ -240,9 +407,9 @@ export class PostTabs {
                             "location": "global",
                             "id": "global::Promise"
                         },
-                        "HTMLPostTabHeaderElement": {
+                        "HTMLPostTabItemElement": {
                             "location": "global",
-                            "id": "global::HTMLPostTabHeaderElement"
+                            "id": "global::HTMLPostTabItemElement"
                         }
                     },
                     "return": "Promise<void>"
@@ -255,4 +422,10 @@ export class PostTabs {
         };
     }
     static get elementRef() { return "host"; }
+    static get watchers() {
+        return [{
+                "propName": "label",
+                "methodName": "validateLabel"
+            }];
+    }
 }

package/dist/collection/components/post-togglebutton/post-togglebutton.js

@@ -26,7 +26,7 @@ export class PostTogglebutton {
         this.host.addEventListener('keydown', (e) => this.handleKeydown(e));
     }
     render() {
-        return (h(Host, { key: 'ecd5772b09be8842e5c6fc3bf34932b27d90c533', "data-version": version, role: "button", tabindex: "0", "aria-pressed": this.toggled.toString() }, h("slot", { key: '3bb32b33155e71ced9375afb5a26d1d4e63a83c8' })));
+        return (h(Host, { key: 'e0708bda008257aeab8e9ad82c33c66eff4aedb6', "data-version": version, role: "button", tabindex: "0", "aria-pressed": this.toggled.toString() }, h("slot", { key: 'a10862573155edbef1a88bd8a1f9f8abf9dbe4c0' })));
     }
     static get is() { return "post-togglebutton"; }
     static get encapsulation() { return "shadow"; }
@@ -44,7 +44,6 @@ export class PostTogglebutton {
         return {
             "toggled": {
                 "type": "boolean",
-                "attribute": "toggled",
                 "mutable": true,
                 "complexType": {
                     "original": "boolean",
@@ -60,6 +59,7 @@ export class PostTogglebutton {
                 "getter": false,
                 "setter": false,
                 "reflect": false,
+                "attribute": "toggled",
                 "defaultValue": "false"
             }
         };

package/dist/collection/components/post-tooltip/post-tooltip.js

@@ -39,7 +39,7 @@ export class PostTooltip {
     async show(target) {
         if (this.open)
             return;
-        this.popoverRef.show(target);
+        await this.popoverRef.show(target);
     }
     /**
      * Programmatically hide this tooltip.
@@ -59,12 +59,12 @@ export class PostTooltip {
      * Set the open state based on the toggle event.
      * @param e Popovercontainer toggle event
      */
-    handleToggle(e) {
-        this.open = e.detail.isOpen;
+    handleBeforeToggle(e) {
+        this.open = e.detail.willOpen;
     }
     render() {
         const popoverClass = `${this.arrow ? 'has-arrow' : ''}`;
-        return (h(Host, { key: 'ebc25bd8a9615a13be82d58f246b5a5d42113cf2', "data-version": version }, h("post-popovercontainer", { key: 'dba7a96c1f354752475a6f1d9116b0097dddf320', safeSpace: "trapezoid", class: popoverClass, role: "tooltip", arrow: this.arrow, animation: this.animation, placement: this.placement, onPostToggle: e => this.handleToggle(e), ref: (el) => (this.popoverRef = el) }, h("slot", { key: '537370b88912d323a72ee074767b4cf2b4bc1b57' }))));
+        return (h(Host, { key: '5de53c10c2556ddb974a65ba06e27ccc99311762', "data-version": version }, h("post-popovercontainer", { key: 'ae3a26fc69d983884eb5aee2b024e74d91983c73', safeSpace: "trapezoid", class: popoverClass, role: "tooltip", arrow: this.arrow, placement: this.placement, onPostBeforeToggle: e => this.handleBeforeToggle(e), ref: (el) => (this.popoverRef = el) }, h("slot", { key: '1fd537504554e094894f8549de5c29c515322866' }))));
     }
     static get is() { return "post-tooltip"; }
     static get encapsulation() { return "shadow"; }
@@ -82,7 +82,6 @@ export class PostTooltip {
         return {
             "placement": {
                 "type": "string",
-                "attribute": "placement",
                 "mutable": false,
                 "complexType": {
                     "original": "Placement",
@@ -91,7 +90,8 @@ export class PostTooltip {
                         "Placement": {
                             "location": "import",
                             "path": "@floating-ui/dom",
-                            "id": "../../node_modules/.pnpm/@floating-ui+dom@1.7.4/node_modules/@floating-ui/dom/dist/floating-ui.dom.d.ts::Placement"
+                            "id": "../../node_modules/.pnpm/@floating-ui+dom@1.7.4/node_modules/@floating-ui/dom/dist/floating-ui.dom.d.mts::Placement",
+                            "referenceLocation": "Placement"
                         }
                     }
                 },
@@ -104,11 +104,11 @@ export class PostTooltip {
                 "getter": false,
                 "setter": false,
                 "reflect": false,
+                "attribute": "placement",
                 "defaultValue": "'top'"
             },
             "arrow": {
                 "type": "boolean",
-                "attribute": "arrow",
                 "mutable": false,
                 "complexType": {
                     "original": "boolean",
@@ -124,30 +124,11 @@ export class PostTooltip {
                 "getter": false,
                 "setter": false,
                 "reflect": false,
+                "attribute": "arrow",
                 "defaultValue": "false"
             },
-            "animation": {
-                "type": "string",
-                "attribute": "animation",
-                "mutable": false,
-                "complexType": {
-                    "original": "'pop-in'",
-                    "resolved": "\"pop-in\"",
-                    "references": {}
-                },
-                "required": false,
-                "optional": true,
-                "docs": {
-                    "tags": [],
-                    "text": "Choose a tooltip animation"
-                },
-                "getter": false,
-                "setter": false,
-                "reflect": false
-            },
             "open": {
                 "type": "boolean",
-                "attribute": "open",
                 "mutable": true,
                 "complexType": {
                     "original": "boolean",
@@ -163,6 +144,7 @@ export class PostTooltip {
                 "getter": false,
                 "setter": false,
                 "reflect": true,
+                "attribute": "open",
                 "defaultValue": "false"
             }
         };

package/dist/collection/components/post-tooltip-trigger/post-tooltip-trigger.js

@@ -169,7 +169,7 @@ export class PostTooltipTrigger {
         this.tooltip?.hide();
     }
     render() {
-        return (h(Host, { key: '48246523aabaf1851e05d0273346d3e26e7ad866', "data-version": version }, h("slot", { key: '0442aeadddd59642c317b6f10c93008adf3e6585', onSlotchange: () => this.handleSlotChange() })));
+        return (h(Host, { key: '4f6165e23284794b677748c495401ed7c110d134', "data-version": version }, h("slot", { key: '87a8d412ed0e3fb145853aebb9426dfe13677853', onSlotchange: () => this.handleSlotChange() })));
     }
     static get is() { return "post-tooltip-trigger"; }
     static get encapsulation() { return "shadow"; }
@@ -187,7 +187,6 @@ export class PostTooltipTrigger {
         return {
             "for": {
                 "type": "string",
-                "attribute": "for",
                 "mutable": false,
                 "complexType": {
                     "original": "string",
@@ -202,11 +201,11 @@ export class PostTooltipTrigger {
                 },
                 "getter": false,
                 "setter": false,
-                "reflect": true
+                "reflect": true,
+                "attribute": "for"
             },
             "delay": {
                 "type": "number",
-                "attribute": "delay",
                 "mutable": false,
                 "complexType": {
                     "original": "number",
@@ -222,6 +221,7 @@ export class PostTooltipTrigger {
                 "getter": false,
                 "setter": false,
                 "reflect": false,
+                "attribute": "delay",
                 "defaultValue": "0"
             }
         };

package/dist/collection/utils/environment.js

@@ -1,2 +1,47 @@
-export const IS_SERVER = typeof window === 'undefined';
-export const IS_BROWSER = !IS_SERVER;
+/**
+ * Environment detection helper
+ *
+ * Goal: Distinguish between real browser execution and Stencil's server-side
+ * hydration context. During SSR/hydration Stencil provides a mocked `window`
+ * (Domino / JSDOM–like) so naive checks (e.g. `typeof window !== 'undefined'`)
+ * incorrectly classify the environment as a browser.
+ *
+ * Detection strategy:
+ * - Stencils hydrate context uses a hardcoded user agent string ('MockNavigator')
+ *   and origin ('http://mockdoc.stenciljs.com') for its mocked `window` object.
+ *   We can use this to identify the hydrate context.
+ * - Stencils unit test context also uses the same hardcoded user agent string,
+ *   but a differnet value for the origin.
+ *   That's why comparing the origin is aboslutely mandatory.
+ * - Since we test the hydrate app in the test context, the origin is getting
+ *   overwritten by the test setup, leading to a false positive in the
+ *   `isHydrateApp` detection.
+ *   To circumvent this, we use a global flag (`isHydrateAppTestEnv`),
+ *   that we set/reset during the server test, so we can correctly identify
+ *   the hydrate app in the test context.
+ *   As a drawback, we can't properly test if the hydrate app is detected as
+ *   expected, in a real world scenario (elsewhere than in our tests).
+ */
+const MOCKED_USERAGENT = 'MockNavigator';
+const MOCKED_ORIGIN = 'http://mockdoc.stenciljs.com';
+const isNodeEnv = typeof global !== 'undefined';
+const hasWindow = typeof window !== 'undefined';
+const isMockedUserAgent = hasWindow && window.navigator.userAgent === MOCKED_USERAGENT;
+const isMockedOrigin = hasWindow && window.location.origin === MOCKED_ORIGIN;
+/**
+ * This is the natural hydrate app environment
+ * Is `true` if the hydrate app runs on server
+ */
+const isHydrateAppEnv = isNodeEnv && isMockedUserAgent && isMockedOrigin;
+/**
+ * This is the test app server test env
+ * Is `true` if the server unit test runs (`false` if the browser unit test runs)
+ */
+const isTestAppServerTestEnv = isNodeEnv && isMockedUserAgent && global.IS_HYDRATEAPP_SERVERTEST;
+/**
+ * This is the final hydrate app flag
+ * if it`s `true`, IS_BROWSER equals `false` and IS_SERVER equals `true
+ */
+const isHydrateApp = isHydrateAppEnv || isTestAppServerTestEnv;
+export const IS_BROWSER = hasWindow && !isHydrateApp;
+export const IS_SERVER = !IS_BROWSER;