@watermarkinsights/ripple 5.32.1-alpha.0 → 5.32.1-alpha.2

package/dist/cjs/{app-globals-9419c1cd.js → app-globals-4ac5459c.js}

@@ -2,7 +2,7 @@
 
 require('./index-bb947bd5.js');
 
-const version = "5.32.1-alpha.0";
+const version = "5.32.1-alpha.2";
 
 // PRINT RIPPLE VERSION IN CONSOLE
 // test envs return 0 for plugin.length

package/dist/cjs/loader.cjs.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 const index = require('./index-bb947bd5.js');
-const appGlobals = require('./app-globals-9419c1cd.js');
+const appGlobals = require('./app-globals-4ac5459c.js');
 
 const defineCustomElements = async (win, options) => {
   if (typeof window === 'undefined') return undefined;

package/dist/cjs/ripple.cjs.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 const index = require('./index-bb947bd5.js');
-const appGlobals = require('./app-globals-9419c1cd.js');
+const appGlobals = require('./app-globals-4ac5459c.js');
 
 /*
  Stencil Client Patch Browser v4.21.0 | MIT Licensed | https://stenciljs.com

package/dist/cjs/wm-navigation_3.cjs.entry.js

@@ -106,9 +106,9 @@ const Navigation = class {
             } }));
     }
     render() {
-        return (index.h(index.Host, { key: '38f20313b339a81259115b164fee7a43f1c4efe5', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (index.h("div", { key: '8630d032614a02068dbcf650d304f6569e00df50', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), index.h("div", { key: '1657807eea4bb2687b5d18c4cb96448110cfa740', class: "tray" }, index.h("div", { key: '92ff3381acb3f959c3f63ca4d20b3e2e51cb81f7', class: "toggle-wrapper" }, index.h("wm-button", { key: 'e20e007c8d77d69ad529cd6d3cc4fafbdb1fc2f1', ref: (el) => (this.toggleEl = el), class: "toggle", "button-type": "navigational", icon: this.open ? "#close" : "#menu", "icon-size": "2rem", tooltip: this.open ? intl.globalMessages.close : intl.globalMessages.open, "tooltip-position": "right", tabIndex: this.open ? undefined : -1, onClick: () => {
+        return (index.h(index.Host, { key: '455ebcf50bec917e657714bb56cd72fc87f7212b', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (index.h("div", { key: 'b9640ea2937c9ab2b33a5f2a287eb50a4678c7d5', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), index.h("div", { key: '157f8f00912c6a35816e7f2aa93bff4e64abea0e', class: "tray" }, index.h("div", { key: 'a08e2258ee9bde6c00e7d59dc655f1b42f45d2ce', class: "toggle-wrapper" }, index.h("wm-button", { key: '72b866b11f2f3292201ed695c77f90ba689c3916', ref: (el) => (this.toggleEl = el), class: "toggle", "button-type": "navigational", icon: this.open ? "#close" : "#menu", "icon-size": "2rem", tooltip: this.open ? intl.globalMessages.close : intl.globalMessages.open, "tooltip-position": "right", tabIndex: this.open ? undefined : -1, onClick: () => {
                 this.open = !this.open;
-            } })), index.h("ul", { key: 'e5ec6a2303ff3def1ddd4f3d5199c93a01895793', class: "navlist" }, index.h("slot", { key: 'b29379969f84e1cea3a3918ba97168420b1c4cbe' }))), this.isCollapsible && (index.h("div", { key: '176f724b791b7792caa5b5b519e79f48ccee2f6b', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
+            } })), index.h("ul", { key: '3f51e76d253adfc22c669d8e2a0675e6552077f7', class: "navlist" }, index.h("slot", { key: '1d150172af4888f51a71177a91c0b0069802f6de' }))), this.isCollapsible && (index.h("div", { key: '2526aebc0b57306d11cb1627e2db83db360f11fe', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
     }
     static get delegatesFocus() { return true; }
     get el() { return index.getElement(this); }
@@ -157,7 +157,7 @@ const NavigationHamburger = class {
         this.wmNavigationHamburgerClicked.emit();
     }
     render() {
-        return (index.h(index.Host, { key: '966bcd988f8ee460899519969a759ffb16459baa', class: `hamburger ${this.open ? "nav-open" : "nav-closed"}` }, index.h("button", { key: 'b1e5c3cd46106943102bf5509a9251953b164c56', "aria-expanded": this.open, "aria-label": this.showNavMessage, onMouseEnter: () => functions.showTooltip("right", this.el, this.showNavMessage), onMouseLeave: () => functions.hideTooltip(), onFocus: () => this.isTabbing && functions.showTooltip("right", this.el, this.showNavMessage), onBlur: () => functions.hideTooltip(), onClick: () => this.handleClick() }, index.h("span", { key: 'a50f398cbdde9271cab48e6bc4eb9013fe8b4ba4', class: "svg-icon svg-menu" }))));
+        return (index.h(index.Host, { key: '7e1cb12ca9c50ce843f5ac08df000df0e641e492', class: `hamburger ${this.open ? "nav-open" : "nav-closed"}` }, index.h("button", { key: '2a385a09660705dfe0d2937d65ab4f527cbccf9d', "aria-expanded": this.open, "aria-label": this.showNavMessage, onMouseEnter: () => functions.showTooltip("right", this.el, this.showNavMessage), onMouseLeave: () => functions.hideTooltip(), onFocus: () => this.isTabbing && functions.showTooltip("right", this.el, this.showNavMessage), onBlur: () => functions.hideTooltip(), onClick: () => this.handleClick() }, index.h("span", { key: '6b644ad886eeb4f50741a85ee53c12e1abc81911', class: "svg-icon svg-menu" }))));
     }
     static get delegatesFocus() { return true; }
     get el() { return index.getElement(this); }

package/dist/collection/components/wm-navigation/wm-navigation-hamburger.js

@@ -2,8 +2,11 @@ import { h, Host } from "@stencil/core";
 import { intl, showTooltip, hideTooltip } from "../../global/functions";
 /**
  * Toggle button for the collapsible wm-navigation sidebar. Renders a hamburger/menu icon
- * button that communicates with wm-navigation via window events. Place immediately before
- * the associated wm-navigation element in the DOM.
+ * button that communicates with wm-navigation via a window event and a document-wide lookup,
+ * not DOM adjacency — place it wherever the page's header needs it, typically at the header's
+ * leading edge, before the logo.
+ *
+ * @category Navigation
  *
  * @keyboardInteraction
  * - **Enter / Space**: Toggles the navigation open/closed.
@@ -15,15 +18,31 @@ import { intl, showTooltip, hideTooltip } from "../../global/functions";
  *
  * @usageNotes
  * - `nav-id` is required; it must match the `id` on the associated wm-navigation element.
- * - Place this component immediately before the wm-navigation element in the DOM.
+ * - Renders nothing and takes no layout space on viewports 1024px and wider (its internal
+ *   button is hidden there). On narrower viewports the host is exactly a 60x60px box with the
+ *   icon centered inside; that sizing already satisfies touch-target minimums, so don't add
+ *   further leading margin or padding on the host for that — doing so stacks on top of the
+ *   component's own and opens a visible gap at the header's outer edge. The box reserves no
+ *   space on its trailing side, though — spacing between it and the next header element
+ *   (typically a logo) is still up to the app's own header layout to provide.
+ * - The example below only illustrates the `nav-id`/`id` contract. For the full page
+ *   placement — header, logo, and the `<main>` sidebar layout — see wm-navigation's
+ *   "Basic navigation" example.
  *
- * @example {html} Basic hamburger
+ * @example {html} nav-id / id pairing
  * <wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
  * <wm-navigation id="main-nav">...</wm-navigation>
  *
- * @example {react} Basic hamburger
+ * @example {react} navId / id pairing
  * <WmNavigationHamburger navId="main-nav" />
  * <WmNavigation id="main-nav">...</WmNavigation>
+ *
+ * @requiredSetup
+ * - `wm-navigation` — required companion; this component's `nav-id` (required) must match
+ *   that element's `id`. No handler is needed for the toggle itself — clicking this button
+ *   emits `wmNavigationHamburgerClicked` on `window`, which wm-navigation listens for and
+ *   toggles its own `open` state — but without a matching `nav-id`/`id` pair, `aria-controls`
+ *   and the toggle both silently fail to connect.
  */
 export class NavigationHamburger {
     constructor() {
@@ -59,7 +78,7 @@ export class NavigationHamburger {
         this.wmNavigationHamburgerClicked.emit();
     }
     render() {
-        return (h(Host, { key: '966bcd988f8ee460899519969a759ffb16459baa', class: `hamburger ${this.open ? "nav-open" : "nav-closed"}` }, h("button", { key: 'b1e5c3cd46106943102bf5509a9251953b164c56', "aria-expanded": this.open, "aria-label": this.showNavMessage, onMouseEnter: () => showTooltip("right", this.el, this.showNavMessage), onMouseLeave: () => hideTooltip(), onFocus: () => this.isTabbing && showTooltip("right", this.el, this.showNavMessage), onBlur: () => hideTooltip(), onClick: () => this.handleClick() }, h("span", { key: 'a50f398cbdde9271cab48e6bc4eb9013fe8b4ba4', class: "svg-icon svg-menu" }))));
+        return (h(Host, { key: '7e1cb12ca9c50ce843f5ac08df000df0e641e492', class: `hamburger ${this.open ? "nav-open" : "nav-closed"}` }, h("button", { key: '2a385a09660705dfe0d2937d65ab4f527cbccf9d', "aria-expanded": this.open, "aria-label": this.showNavMessage, onMouseEnter: () => showTooltip("right", this.el, this.showNavMessage), onMouseLeave: () => hideTooltip(), onFocus: () => this.isTabbing && showTooltip("right", this.el, this.showNavMessage), onBlur: () => hideTooltip(), onClick: () => this.handleClick() }, h("span", { key: '6b644ad886eeb4f50741a85ee53c12e1abc81911', class: "svg-icon svg-menu" }))));
     }
     static get is() { return "wm-navigation-hamburger"; }
     static get encapsulation() { return "shadow"; }

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

@@ -4,7 +4,9 @@ import { globalMessages } from "../../global/intl";
 /**
  * Sidebar navigation that collapses into a hamburger menu on viewports narrower than 1024px.
  * Contains wm-navigation-item children and works alongside an external wm-navigation-hamburger
- * toggle. Must be placed in the DOM after `<header>` and before `<main>`.
+ * toggle. Render it as the first child of `<main>`, with the page's actual content in a sibling
+ * element — a flex or grid `<main>` lets the navigation sit alongside that content as a
+ * sidebar on viewports 1024px and wider, with no extra positioning needed.
  *
  * @category Navigation
  *
@@ -23,29 +25,100 @@ import { globalMessages } from "../../global/intl";
  *   address bar via a `focus` listener on `document.body`.
  *
  * @usageNotes
- * - Use `wm-navigation-hamburger` (a separate component) as the external toggle; it communicates
- *   with wm-navigation via the `wmNavigationHamburgerClicked` window event.
- * - `open` can be set initially to `true` to start the navigation expanded.
- * - Navigation and main content scroll independently — no additional overflow handling is needed.
+ * - Use `wm-navigation-hamburger` (a separate component) as the external toggle. It communicates
+ *   with wm-navigation via the `wmNavigationHamburgerClicked` window event and a document-wide
+ *   lookup, so it does not need to be a DOM sibling of wm-navigation — place it in the page
+ *   header instead, at the leading edge before the logo. It already reserves its own
+ *   touch-target padding on narrower viewports, so don't add further leading margin or padding
+ *   on the host for that — but the gap between it and the logo is still the header's own layout
+ *   to provide; the hamburger's box reserves no trailing space of its own (see
+ *   wm-navigation-hamburger's docs).
+ * - `open` can be set initially to `true` to start the navigation expanded, in place of
+ *   waiting for wm-navigation-hamburger's toggle.
  *
  * Required host setup:
  * - Never set `display: none` or `visibility: hidden` on the host element or its wrapper
  *   container. The component manages its own visibility internally, and hiding the container
  *   from the outside blocks the overlay from appearing when the hamburger is triggered.
+ * - Give the element that wraps wm-navigation and the page content (commonly `<main>`) a flex
+ *   or grid layout, and leave cross-axis alignment at its default (`align-items: stretch`,
+ *   the default for both). This component's elevated surface, including its box-shadow, is
+ *   sized to the host element's own height — overriding the default (e.g. `align-items:
+ *   flex-start` or `center`) shrinks the host down to its item list's height, so the shadow
+ *   clips partway down the page instead of running full height.
+ * - That flex/grid wrapper also needs a bounded height for real independent scrolling —
+ *   `display: flex; align-items: stretch` alone does not create one, it only makes the
+ *   navigation match whatever height the wrapper happens to end up. Give an ancestor
+ *   (typically an app-shell wrapping the header and this wrapper) a fixed height such as
+ *   `100vh`, make the wrapper itself `flex: 1; min-height: 0` within that shell, and give the
+ *   actual content pane its own `overflow-y: auto; min-height: 0`. Skip the bounded height and
+ *   the wrapper just grows to fit its tallest child — the whole document scrolls as one long
+ *   page instead, and that also defeats this component's own item list, which needs that same
+ *   constraint to scroll internally rather than just growing taller.
  *
  * @example {html} Basic navigation
- * <wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
- * <wm-navigation id="main-nav">
- *   <wm-navigation-item href="/dashboard" text="Dashboard" active></wm-navigation-item>
- *   <wm-navigation-item href="/reports" text="Reports"></wm-navigation-item>
- * </wm-navigation>
+ * <style>
+ *   .app-shell {
+ *     display: flex;
+ *     flex-direction: column;
+ *     height: 100vh;
+ *   }
+ *   .app-header {
+ *     flex: 0 0 auto;
+ *   }
+ *   .app-main {
+ *     display: flex;
+ *     align-items: stretch;
+ *     flex: 1 1 auto;
+ *     min-height: 0;
+ *   }
+ *   .app-main__content {
+ *     overflow-y: auto;
+ *     min-height: 0;
+ *   }
+ * </style>
+ * <div class="app-shell">
+ *   <header class="app-header">
+ *     <wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
+ *     <a class="app-header__logo" href="/">App Name</a>
+ *   </header>
+ *   <main class="app-main">
+ *     <wm-navigation id="main-nav">
+ *       <wm-navigation-item href="/dashboard" text="Dashboard" active></wm-navigation-item>
+ *       <wm-navigation-item href="/reports" text="Reports"></wm-navigation-item>
+ *     </wm-navigation>
+ *     <div class="app-main__content">Page content</div>
+ *   </main>
+ * </div>
  *
  * @example {react} Basic navigation
- * <WmNavigationHamburger navId="main-nav" />
- * <WmNavigation id="main-nav">
- *   <WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
- *   <WmNavigationItem href="/reports" text="Reports" />
- * </WmNavigation>
+ * <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+ *   <header className="app-header">
+ *     <WmNavigationHamburger navId="main-nav" />
+ *     <a className="app-header__logo" href="/">App Name</a>
+ *   </header>
+ *   <main
+ *     className="app-main"
+ *     style={{ display: "flex", alignItems: "stretch", flex: "1 1 auto", minHeight: 0 }}
+ *   >
+ *     <WmNavigation id="main-nav">
+ *       <WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
+ *       <WmNavigationItem href="/reports" text="Reports" />
+ *     </WmNavigation>
+ *     <div className="app-main__content" style={{ overflowY: "auto", minHeight: 0 }}>
+ *       Page content
+ *     </div>
+ *   </main>
+ * </div>
+ *
+ * @requiredSetup
+ * - `wm-navigation-item` — slot at least one as a child; each supplies a link the collapsible
+ *   menu and the persistent sidebar both render.
+ * - `wm-navigation-hamburger` — required for collapsible viewports; set its `nav-id` to match
+ *   this component's `id`. No handler is needed for the pairing itself — wm-navigation listens
+ *   for `wmNavigationHamburgerClicked` on `window` and toggles `open` itself — but without a
+ *   matching `nav-id`/`id` pair, the hamburger's `aria-controls` and the toggle both silently
+ *   fail to connect.
  *
  */
 export class Navigation {
@@ -143,9 +216,9 @@ export class Navigation {
             } }));
     }
     render() {
-        return (h(Host, { key: '38f20313b339a81259115b164fee7a43f1c4efe5', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (h("div", { key: '8630d032614a02068dbcf650d304f6569e00df50', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), h("div", { key: '1657807eea4bb2687b5d18c4cb96448110cfa740', class: "tray" }, h("div", { key: '92ff3381acb3f959c3f63ca4d20b3e2e51cb81f7', class: "toggle-wrapper" }, h("wm-button", { key: 'e20e007c8d77d69ad529cd6d3cc4fafbdb1fc2f1', ref: (el) => (this.toggleEl = el), class: "toggle", "button-type": "navigational", icon: this.open ? "#close" : "#menu", "icon-size": "2rem", tooltip: this.open ? globalMessages.close : globalMessages.open, "tooltip-position": "right", tabIndex: this.open ? undefined : -1, onClick: () => {
+        return (h(Host, { key: '455ebcf50bec917e657714bb56cd72fc87f7212b', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (h("div", { key: 'b9640ea2937c9ab2b33a5f2a287eb50a4678c7d5', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), h("div", { key: '157f8f00912c6a35816e7f2aa93bff4e64abea0e', class: "tray" }, h("div", { key: 'a08e2258ee9bde6c00e7d59dc655f1b42f45d2ce', class: "toggle-wrapper" }, h("wm-button", { key: '72b866b11f2f3292201ed695c77f90ba689c3916', ref: (el) => (this.toggleEl = el), class: "toggle", "button-type": "navigational", icon: this.open ? "#close" : "#menu", "icon-size": "2rem", tooltip: this.open ? globalMessages.close : globalMessages.open, "tooltip-position": "right", tabIndex: this.open ? undefined : -1, onClick: () => {
                 this.open = !this.open;
-            } })), h("ul", { key: 'e5ec6a2303ff3def1ddd4f3d5199c93a01895793', class: "navlist" }, h("slot", { key: 'b29379969f84e1cea3a3918ba97168420b1c4cbe' }))), this.isCollapsible && (h("div", { key: '176f724b791b7792caa5b5b519e79f48ccee2f6b', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
+            } })), h("ul", { key: '3f51e76d253adfc22c669d8e2a0675e6552077f7', class: "navlist" }, h("slot", { key: '1d150172af4888f51a71177a91c0b0069802f6de' }))), this.isCollapsible && (h("div", { key: '2526aebc0b57306d11cb1627e2db83db360f11fe', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
     }
     static get is() { return "wm-navigation"; }
     static get encapsulation() { return "shadow"; }

package/dist/docs/docs.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-08-28T17:34:39",
+  "timestamp": "2026-09-08T16:58:32",
   "compiler": {
     "name": "@stencil/core",
     "version": "4.21.0",
@@ -7663,7 +7663,7 @@
       "filePath": "src/components/wm-navigation/wm-navigation.tsx",
       "encapsulation": "shadow",
       "tag": "wm-navigation",
-      "docs": "Sidebar navigation that collapses into a hamburger menu on viewports narrower than 1024px.\nContains wm-navigation-item children and works alongside an external wm-navigation-hamburger\ntoggle. Must be placed in the DOM after `<header>` and before `<main>`.",
+      "docs": "Sidebar navigation that collapses into a hamburger menu on viewports narrower than 1024px.\nContains wm-navigation-item children and works alongside an external wm-navigation-hamburger\ntoggle. Render it as the first child of `<main>`, with the page's actual content in a sibling\nelement — a flex or grid `<main>` lets the navigation sit alongside that content as a\nsidebar on viewports 1024px and wider, with no extra positioning needed.",
       "docsTags": [
         {
           "name": "category",
@@ -7683,15 +7683,19 @@
         },
         {
           "name": "usageNotes",
-          "text": "- Use `wm-navigation-hamburger` (a separate component) as the external toggle; it communicates\n  with wm-navigation via the `wmNavigationHamburgerClicked` window event.\n- `open` can be set initially to `true` to start the navigation expanded.\n- Navigation and main content scroll independently — no additional overflow handling is needed.\n\nRequired host setup:\n- Never set `display: none` or `visibility: hidden` on the host element or its wrapper\n  container. The component manages its own visibility internally, and hiding the container\n  from the outside blocks the overlay from appearing when the hamburger is triggered."
+          "text": "- Use `wm-navigation-hamburger` (a separate component) as the external toggle. It communicates\n  with wm-navigation via the `wmNavigationHamburgerClicked` window event and a document-wide\n  lookup, so it does not need to be a DOM sibling of wm-navigation — place it in the page\n  header instead, at the leading edge before the logo. It already reserves its own\n  touch-target padding on narrower viewports, so don't add further leading margin or padding\n  on the host for that — but the gap between it and the logo is still the header's own layout\n  to provide; the hamburger's box reserves no trailing space of its own (see\n  wm-navigation-hamburger's docs).\n- `open` can be set initially to `true` to start the navigation expanded, in place of\n  waiting for wm-navigation-hamburger's toggle.\n\nRequired host setup:\n- Never set `display: none` or `visibility: hidden` on the host element or its wrapper\n  container. The component manages its own visibility internally, and hiding the container\n  from the outside blocks the overlay from appearing when the hamburger is triggered.\n- Give the element that wraps wm-navigation and the page content (commonly `<main>`) a flex\n  or grid layout, and leave cross-axis alignment at its default (`align-items: stretch`,\n  the default for both). This component's elevated surface, including its box-shadow, is\n  sized to the host element's own height — overriding the default (e.g. `align-items:\n  flex-start` or `center`) shrinks the host down to its item list's height, so the shadow\n  clips partway down the page instead of running full height.\n- That flex/grid wrapper also needs a bounded height for real independent scrolling —\n  `display: flex; align-items: stretch` alone does not create one, it only makes the\n  navigation match whatever height the wrapper happens to end up. Give an ancestor\n  (typically an app-shell wrapping the header and this wrapper) a fixed height such as\n  `100vh`, make the wrapper itself `flex: 1; min-height: 0` within that shell, and give the\n  actual content pane its own `overflow-y: auto; min-height: 0`. Skip the bounded height and\n  the wrapper just grows to fit its tallest child — the whole document scrolls as one long\n  page instead, and that also defeats this component's own item list, which needs that same\n  constraint to scroll internally rather than just growing taller."
         },
         {
           "name": "example",
-          "text": "{html} Basic navigation\n<wm-navigation-hamburger nav-id=\"main-nav\"></wm-navigation-hamburger>\n<wm-navigation id=\"main-nav\">\n<wm-navigation-item href=\"/dashboard\" text=\"Dashboard\" active></wm-navigation-item>\n<wm-navigation-item href=\"/reports\" text=\"Reports\"></wm-navigation-item>\n</wm-navigation>"
+          "text": "{html} Basic navigation\n<style>\n.app-shell {\ndisplay: flex;\nflex-direction: column;\nheight: 100vh;\n}\n.app-header {\nflex: 0 0 auto;\n}\n.app-main {\ndisplay: flex;\nalign-items: stretch;\nflex: 1 1 auto;\nmin-height: 0;\n}\n.app-main__content {\noverflow-y: auto;\nmin-height: 0;\n}\n</style>\n<div class=\"app-shell\">\n<header class=\"app-header\">\n<wm-navigation-hamburger nav-id=\"main-nav\"></wm-navigation-hamburger>\n<a class=\"app-header__logo\" href=\"/\">App Name</a>\n</header>\n<main class=\"app-main\">\n<wm-navigation id=\"main-nav\">\n<wm-navigation-item href=\"/dashboard\" text=\"Dashboard\" active></wm-navigation-item>\n<wm-navigation-item href=\"/reports\" text=\"Reports\"></wm-navigation-item>\n</wm-navigation>\n<div class=\"app-main__content\">Page content</div>\n</main>\n</div>"
         },
         {
           "name": "example",
-          "text": "{react} Basic navigation\n<WmNavigationHamburger navId=\"main-nav\" />\n<WmNavigation id=\"main-nav\">\n<WmNavigationItem href=\"/dashboard\" text=\"Dashboard\" active={true} />\n<WmNavigationItem href=\"/reports\" text=\"Reports\" />\n</WmNavigation>"
+          "text": "{react} Basic navigation\n<div style={{ display: \"flex\", flexDirection: \"column\", height: \"100vh\" }}>\n<header className=\"app-header\">\n<WmNavigationHamburger navId=\"main-nav\" />\n<a className=\"app-header__logo\" href=\"/\">App Name</a>\n</header>\n<main\nclassName=\"app-main\"\nstyle={{ display: \"flex\", alignItems: \"stretch\", flex: \"1 1 auto\", minHeight: 0 }}\n>\n<WmNavigation id=\"main-nav\">\n<WmNavigationItem href=\"/dashboard\" text=\"Dashboard\" active={true} />\n<WmNavigationItem href=\"/reports\" text=\"Reports\" />\n</WmNavigation>\n<div className=\"app-main__content\" style={{ overflowY: \"auto\", minHeight: 0 }}>\nPage content\n</div>\n</main>\n</div>"
+        },
+        {
+          "name": "requiredSetup",
+          "text": "- `wm-navigation-item` — slot at least one as a child; each supplies a link the collapsible\n  menu and the persistent sidebar both render.\n- `wm-navigation-hamburger` — required for collapsible viewports; set its `nav-id` to match\n  this component's `id`. No handler is needed for the pairing itself — wm-navigation listens\n  for `wmNavigationHamburgerClicked` on `window` and toggles `open` itself — but without a\n  matching `nav-id`/`id` pair, the hamburger's `aria-controls` and the toggle both silently\n  fail to connect."
         }
       ],
       "usage": {},
@@ -7796,8 +7800,12 @@
       "filePath": "src/components/wm-navigation/wm-navigation-hamburger.tsx",
       "encapsulation": "shadow",
       "tag": "wm-navigation-hamburger",
-      "docs": "Toggle button for the collapsible wm-navigation sidebar. Renders a hamburger/menu icon\nbutton that communicates with wm-navigation via window events. Place immediately before\nthe associated wm-navigation element in the DOM.",
+      "docs": "Toggle button for the collapsible wm-navigation sidebar. Renders a hamburger/menu icon\nbutton that communicates with wm-navigation via a window event and a document-wide lookup,\nnot DOM adjacency — place it wherever the page's header needs it, typically at the header's\nleading edge, before the logo.",
       "docsTags": [
+        {
+          "name": "category",
+          "text": "Navigation"
+        },
         {
           "name": "keyboardInteraction",
           "text": "- **Enter / Space**: Toggles the navigation open/closed."
@@ -7808,15 +7816,19 @@
         },
         {
           "name": "usageNotes",
-          "text": "- `nav-id` is required; it must match the `id` on the associated wm-navigation element.\n- Place this component immediately before the wm-navigation element in the DOM."
+          "text": "- `nav-id` is required; it must match the `id` on the associated wm-navigation element.\n- Renders nothing and takes no layout space on viewports 1024px and wider (its internal\n  button is hidden there). On narrower viewports the host is exactly a 60x60px box with the\n  icon centered inside; that sizing already satisfies touch-target minimums, so don't add\n  further leading margin or padding on the host for that — doing so stacks on top of the\n  component's own and opens a visible gap at the header's outer edge. The box reserves no\n  space on its trailing side, though — spacing between it and the next header element\n  (typically a logo) is still up to the app's own header layout to provide.\n- The example below only illustrates the `nav-id`/`id` contract. For the full page\n  placement — header, logo, and the `<main>` sidebar layout — see wm-navigation's\n  \"Basic navigation\" example."
         },
         {
           "name": "example",
-          "text": "{html} Basic hamburger\n<wm-navigation-hamburger nav-id=\"main-nav\"></wm-navigation-hamburger>\n<wm-navigation id=\"main-nav\">...</wm-navigation>"
+          "text": "{html} nav-id / id pairing\n<wm-navigation-hamburger nav-id=\"main-nav\"></wm-navigation-hamburger>\n<wm-navigation id=\"main-nav\">...</wm-navigation>"
         },
         {
           "name": "example",
-          "text": "{react} Basic hamburger\n<WmNavigationHamburger navId=\"main-nav\" />\n<WmNavigation id=\"main-nav\">...</WmNavigation>"
+          "text": "{react} navId / id pairing\n<WmNavigationHamburger navId=\"main-nav\" />\n<WmNavigation id=\"main-nav\">...</WmNavigation>"
+        },
+        {
+          "name": "requiredSetup",
+          "text": "- `wm-navigation` — required companion; this component's `nav-id` (required) must match\n  that element's `id`. No handler is needed for the toggle itself — clicking this button\n  emits `wmNavigationHamburgerClicked` on `window`, which wm-navigation listens for and\n  toggles its own `open` state — but without a matching `nav-id`/`id` pair, `aria-controls`\n  and the toggle both silently fail to connect."
         }
       ],
       "usage": {},

package/dist/docs/props-reference.json

@@ -1085,7 +1085,7 @@
   },
   {
     "tag": "wm-navigation",
-    "description": "Sidebar navigation that collapses into a hamburger menu on viewports narrower than 1024px.\nContains wm-navigation-item children and works alongside an external wm-navigation-hamburger\ntoggle. Must be placed in the DOM after `<header>` and before `<main>`.",
+    "description": "Sidebar navigation that collapses into a hamburger menu on viewports narrower than 1024px.\nContains wm-navigation-item children and works alongside an external wm-navigation-hamburger\ntoggle. Render it as the first child of `<main>`, with the page's actual content in a sibling\nelement — a flex or grid `<main>` lets the navigation sit alongside that content as a\nsidebar on viewports 1024px and wider, with no extra positioning needed.",
     "props": [
       {
         "name": "open",
@@ -1098,7 +1098,7 @@
   },
   {
     "tag": "wm-navigation-hamburger",
-    "description": "Toggle button for the collapsible wm-navigation sidebar. Renders a hamburger/menu icon\nbutton that communicates with wm-navigation via window events. Place immediately before\nthe associated wm-navigation element in the DOM.",
+    "description": "Toggle button for the collapsible wm-navigation sidebar. Renders a hamburger/menu icon\nbutton that communicates with wm-navigation via a window event and a document-wide lookup,\nnot DOM adjacency — place it wherever the page's header needs it, typically at the header's\nleading edge, before the logo.",
     "props": [
       {
         "name": "navId",

package/dist/docs/skill/index.md

@@ -27,6 +27,7 @@
 | **Timepicker** | `wm-timepicker` | `wm-timepicker.md` | Form Inputs |
 | **Uploader** | `wm-uploader` | `wm-uploader.md` | Form Inputs |
 | **Navigation** | `wm-navigation` | `wm-navigation.md` | Navigation |
+| **Navigation Hamburger** | `wm-navigation-hamburger` | `wm-navigation-hamburger.md` | Navigation |
 | **Navigator** | `wm-navigator` | `wm-navigator.md` | Navigation |
 | **Pagination** | `wm-pagination` | `wm-pagination.md` | Navigation |
 | **Tabs** | `wm-tab-list` | `wm-tab-list.md` | Navigation |

package/dist/docs/skill/wm-navigation-hamburger.md

@@ -2,8 +2,9 @@
 - **Element:** `<wm-navigation-hamburger>`
 
 **Purpose:** Toggle button for the collapsible wm-navigation sidebar. Renders a hamburger/menu icon
-button that communicates with wm-navigation via window events. Place immediately before
-the associated wm-navigation element in the DOM.
+button that communicates with wm-navigation via a window event and a document-wide lookup,
+not DOM adjacency -- place it wherever the page's header needs it, typically at the header's
+leading edge, before the logo.
 
 **When to use:**
 
@@ -21,7 +22,16 @@ _None documented_
 **Usage notes:**
 
 - `nav-id` is required; it must match the `id` on the associated wm-navigation element.
-- Place this component immediately before the wm-navigation element in the DOM.
+- Renders nothing and takes no layout space on viewports 1024px and wider (its internal
+  button is hidden there). On narrower viewports the host is exactly a 60x60px box with the
+  icon centered inside; that sizing already satisfies touch-target minimums, so don't add
+  further leading margin or padding on the host for that -- doing so stacks on top of the
+  component's own and opens a visible gap at the header's outer edge. The box reserves no
+  space on its trailing side, though -- spacing between it and the next header element
+  (typically a logo) is still up to the app's own header layout to provide.
+- The example below only illustrates the `nav-id`/`id` contract. For the full page
+  placement -- header, logo, and the `<main>` sidebar layout -- see wm-navigation's
+  "Basic navigation" example.
 
 **Props:**
 - `nav-id` -- The `id` of the associated wm-navigation element. Required for semantic
@@ -31,6 +41,14 @@ linking and for keeping `aria-expanded` in sync with the navigation's open state
 - `wmNavigationHamburgerClicked` -- Fires when the button is clicked. Consumed by the associated wm-navigation
 to toggle its `open` state -- not intended for direct application use.
 
+**Required setup:**
+
+- `wm-navigation` -- required companion; this component's `nav-id` (required) must match
+  that element's `id`. No handler is needed for the toggle itself -- clicking this button
+  emits `wmNavigationHamburgerClicked` on `window`, which wm-navigation listens for and
+  toggles its own `open` state -- but without a matching `nav-id`/`id` pair, `aria-controls`
+  and the toggle both silently fail to connect.
+
 **Accessibility:**
 
 - Rendered as a `<button>` with `aria-expanded` reflecting the navigation's open state.
@@ -46,14 +64,14 @@ to toggle its `open` state -- not intended for direct application use.
 
 **Code example:**
 
-_Basic hamburger_
+_nav-id / id pairing_
 
 ```html
 <wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
 <wm-navigation id="main-nav">...</wm-navigation>
 ```
 
-_Basic hamburger_
+_navId / id pairing_
 
 ```react
 <WmNavigationHamburger navId="main-nav" />

package/dist/docs/skill/wm-navigation.md

@@ -3,7 +3,9 @@
 
 **Purpose:** Sidebar navigation that collapses into a hamburger menu on viewports narrower than 1024px.
 Contains wm-navigation-item children and works alongside an external wm-navigation-hamburger
-toggle. Must be placed in the DOM after `<header>` and before `<main>`.
+toggle. Render it as the first child of `<main>`, with the page's actual content in a sibling
+element -- a flex or grid `<main>` lets the navigation sit alongside that content as a
+sidebar on viewports 1024px and wider, with no extra positioning needed.
 
 **When to use:**
 
@@ -20,15 +22,36 @@ _None documented_
 
 **Usage notes:**
 
-- Use `wm-navigation-hamburger` (a separate component) as the external toggle; it communicates
-  with wm-navigation via the `wmNavigationHamburgerClicked` window event.
-- `open` can be set initially to `true` to start the navigation expanded.
-- Navigation and main content scroll independently -- no additional overflow handling is needed.
+- Use `wm-navigation-hamburger` (a separate component) as the external toggle. It communicates
+  with wm-navigation via the `wmNavigationHamburgerClicked` window event and a document-wide
+  lookup, so it does not need to be a DOM sibling of wm-navigation -- place it in the page
+  header instead, at the leading edge before the logo. It already reserves its own
+  touch-target padding on narrower viewports, so don't add further leading margin or padding
+  on the host for that -- but the gap between it and the logo is still the header's own layout
+  to provide; the hamburger's box reserves no trailing space of its own (see
+  wm-navigation-hamburger's docs).
+- `open` can be set initially to `true` to start the navigation expanded, in place of
+  waiting for wm-navigation-hamburger's toggle.
 
 Required host setup:
 - Never set `display: none` or `visibility: hidden` on the host element or its wrapper
   container. The component manages its own visibility internally, and hiding the container
   from the outside blocks the overlay from appearing when the hamburger is triggered.
+- Give the element that wraps wm-navigation and the page content (commonly `<main>`) a flex
+  or grid layout, and leave cross-axis alignment at its default (`align-items: stretch`,
+  the default for both). This component's elevated surface, including its box-shadow, is
+  sized to the host element's own height -- overriding the default (e.g. `align-items:
+  flex-start` or `center`) shrinks the host down to its item list's height, so the shadow
+  clips partway down the page instead of running full height.
+- That flex/grid wrapper also needs a bounded height for real independent scrolling --
+  `display: flex; align-items: stretch` alone does not create one, it only makes the
+  navigation match whatever height the wrapper happens to end up. Give an ancestor
+  (typically an app-shell wrapping the header and this wrapper) a fixed height such as
+  `100vh`, make the wrapper itself `flex: 1; min-height: 0` within that shell, and give the
+  actual content pane its own `overflow-y: auto; min-height: 0`. Skip the bounded height and
+  the wrapper just grows to fit its tallest child -- the whole document scrolls as one long
+  page instead, and that also defeats this component's own item list, which needs that same
+  constraint to scroll internally rather than just growing taller.
 
 **Props:**
 - `open` -- Controls the open/closed state of the collapsible navigation. Has no effect
@@ -41,6 +64,16 @@ on viewports wider than 1024px where the navigation is always visible. _(default
 - `wmNavigationStateChanged` -- Fires when the collapsible navigation opens or closes. Consumed by
 wm-navigation-hamburger to keep its `aria-expanded` state in sync.
 
+**Required setup:**
+
+- `wm-navigation-item` -- slot at least one as a child; each supplies a link the collapsible
+  menu and the persistent sidebar both render.
+- `wm-navigation-hamburger` -- required for collapsible viewports; set its `nav-id` to match
+  this component's `id`. No handler is needed for the pairing itself -- wm-navigation listens
+  for `wmNavigationHamburgerClicked` on `window` and toggles `open` itself -- but without a
+  matching `nav-id`/`id` pair, the hamburger's `aria-controls` and the toggle both silently
+  fail to connect.
+
 **Accessibility:**
 
 - Rendered with `role="navigation"` and an `aria-label` of "Main".
@@ -64,19 +97,60 @@ wm-navigation-hamburger to keep its `aria-expanded` state in sync.
 _Basic navigation_
 
 ```html
+<style>
+.app-shell {
+display: flex;
+flex-direction: column;
+height: 100vh;
+}
+.app-header {
+flex: 0 0 auto;
+}
+.app-main {
+display: flex;
+align-items: stretch;
+flex: 1 1 auto;
+min-height: 0;
+}
+.app-main__content {
+overflow-y: auto;
+min-height: 0;
+}
+</style>
+<div class="app-shell">
+<header class="app-header">
 <wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
+<a class="app-header__logo" href="/">App Name</a>
+</header>
+<main class="app-main">
 <wm-navigation id="main-nav">
 <wm-navigation-item href="/dashboard" text="Dashboard" active></wm-navigation-item>
 <wm-navigation-item href="/reports" text="Reports"></wm-navigation-item>
 </wm-navigation>
+<div class="app-main__content">Page content</div>
+</main>
+</div>
 ```
 
 _Basic navigation_
 
 ```react
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+<header className="app-header">
 <WmNavigationHamburger navId="main-nav" />
+<a className="app-header__logo" href="/">App Name</a>
+</header>
+<main
+className="app-main"
+style={{ display: "flex", alignItems: "stretch", flex: "1 1 auto", minHeight: 0 }}
+>
 <WmNavigation id="main-nav">
 <WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
 <WmNavigationItem href="/reports" text="Reports" />
 </WmNavigation>
+<div className="app-main__content" style={{ overflowY: "auto", minHeight: 0 }}>
+Page content
+</div>
+</main>
+</div>
 ```

package/dist/esm/{app-globals-12f21c79.js → app-globals-10d4c715.js}

@@ -1,6 +1,6 @@
 import './index-3425d80d.js';
 
-const version = "5.32.1-alpha.0";
+const version = "5.32.1-alpha.2";
 
 // PRINT RIPPLE VERSION IN CONSOLE
 // test envs return 0 for plugin.length

package/dist/esm/loader.js

@@ -1,6 +1,6 @@
 import { b as bootstrapLazy } from './index-3425d80d.js';
 export { s as setNonce } from './index-3425d80d.js';
-import { g as globalScripts } from './app-globals-12f21c79.js';
+import { g as globalScripts } from './app-globals-10d4c715.js';
 
 const defineCustomElements = async (win, options) => {
   if (typeof window === 'undefined') return undefined;

package/dist/esm/ripple.js

@@ -1,6 +1,6 @@
 import { p as promiseResolve, b as bootstrapLazy } from './index-3425d80d.js';
 export { s as setNonce } from './index-3425d80d.js';
-import { g as globalScripts } from './app-globals-12f21c79.js';
+import { g as globalScripts } from './app-globals-10d4c715.js';
 
 /*
  Stencil Client Patch Browser v4.21.0 | MIT Licensed | https://stenciljs.com