@watermarkinsights/ripple 5.32.1-alpha.1 → 5.32.1-alpha.3

package/dist/cjs/{app-globals-6f8f7d34.js → app-globals-2a95ac29.js}

@@ -2,7 +2,7 @@
 
 require('./index-bb947bd5.js');
 
-const version = "5.32.1-alpha.1";
+const version = "5.32.1-alpha.3";
 
 // 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-6f8f7d34.js');
+const appGlobals = require('./app-globals-2a95ac29.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-6f8f7d34.js');
+const appGlobals = require('./app-globals-2a95ac29.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: '96933040f7f88edf4e52c5e0480712e1f15e8db6', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (index.h("div", { key: '4658a3e22aa96a55dfb5b0211912805b683e26d2', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), index.h("div", { key: 'cb3ae13600538706292ed27eeff3f70e33015975', class: "tray" }, index.h("div", { key: 'df934dfeb30d54294656dde2cfc78c95c6140e65', class: "toggle-wrapper" }, index.h("wm-button", { key: '478b6428b08703302a21f64d7adc58e6788e1803', 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: 'a15b95ca5769e6a996542f3fb0f1edf8928ed4ea', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (index.h("div", { key: 'add1bb58939e3d076c7890aa1cb3efd932f977dc', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), index.h("div", { key: '98491d3d97807417a13b677894ee452e89e9cea8', class: "tray" }, index.h("div", { key: 'cf058b8b33a07598f19318977e26e652304faf4f', class: "toggle-wrapper" }, index.h("wm-button", { key: '7e8d936e3fdc9c718bf9442b6840464a6caddcab', 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: '32035dea4487af347ec5e56c3010bdf8b84d2c12', class: "navlist" }, index.h("slot", { key: 'a3512e42e16da5ad5591fa1f1f5211dc5b1576ee' }))), this.isCollapsible && (index.h("div", { key: '8e77d6376ccc683560ec214d2ec7d694aa417789', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
+            } })), index.h("ul", { key: 'e90219ba02e6a2330095e12ee4793ac82100fc5d', class: "navlist" }, index.h("slot", { key: '83e672cf048480abbef358f8249cb1622e2fad3c' }))), this.isCollapsible && (index.h("div", { key: '3c16362bebb241d693aa6aa8fd7226a34039901d', 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: '6f135919a43b55f7c4fca79d79e9a5c201d84fdd', class: `hamburger ${this.open ? "nav-open" : "nav-closed"}` }, index.h("button", { key: '8d930f77ea878a4f7757084fe45178004cc8a74e', "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: '798de550cd68d4d3b2ce78036206175e3901e1c0', class: "svg-icon svg-menu" }))));
     }
     static get delegatesFocus() { return true; }
     get el() { return index.getElement(this); }
@@ -176,7 +176,7 @@ const NavigationItem = class {
         this.active = undefined;
     }
     render() {
-        return (index.h(index.Host, { key: '5c37c39e27b4602bcc53f2a1e118fb427b7a9a1a', role: "listitem" }, index.h("a", { key: 'ba3e7216ba1a5e7cb8d61dff61b353eeaaddee34', class: `link ${this.active ? "active" : ""}`, href: this.href, onClick: () => this.wmNavigationItemClicked.emit() }, index.h("div", { key: '9a35a2bd7f3474a182e187f8fe4b35904cb00862', class: "icon", "aria-hidden": "true" }, index.h("slot", { key: 'fb6858dafb750fcee200e57757dd86bbfc05cd23' })), index.h("div", { key: '6b2c933f73fd07746c3f3bcb656f9fc9563e88cd', class: "text" }, this.text))));
+        return (index.h(index.Host, { key: 'bbe3c0a165b8d7d4bf036e5a80b23eb11446b90e', role: "listitem" }, index.h("a", { key: '7f4ef86559f368dca39bd7a72ed05daafb539648', class: `link ${this.active ? "active" : ""}`, href: this.href, onClick: () => this.wmNavigationItemClicked.emit() }, index.h("div", { key: '8ae1aae920abe64829e87f2a107f1bf3eb752e50', class: "icon", "aria-hidden": "true" }, index.h("slot", { key: '1da830a8aae16100d5c99b5bfe7e80086f8a7baa' })), index.h("div", { key: '876286ffd8f555d840538a088051faeede3882ae', class: "text" }, this.text))));
     }
     static get delegatesFocus() { return true; }
     get el() { return index.getElement(this); }

package/dist/cjs/wm-tag-input.cjs.entry.js

@@ -327,7 +327,6 @@ const TagInput = class {
         const addedNodes = Array.from(record.addedNodes);
         if (addedNodes.length > 0) {
             this.assignOptionIds();
-            // reassign rather than push: Stencil only re-renders on a state reference change
             const newNodes = addedNodes.filter((n) => !this.tagsList.includes(n));
             if (newNodes.length > 0) {
                 this.tagsList = [...this.tagsList, ...newNodes];
@@ -970,10 +969,10 @@ const TagInput = class {
         }
     }
     render() {
-        return (index.h("div", { key: '0506ec7b7255034f0fa8132d813727a72895b86a', class: `wrapper label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, index.h("div", { key: '8f8726c6d9e1a524b6c9b9aa90dee9748fc93635', class: "label-wrapper" }, index.h("label", { key: '1f9b00a496fcd9923800471cc77e8c9c65111a8b', class: "label", htmlFor: "input", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => functions.hideTooltip() }, this.label), this.labelPosition !== "none" && this.requiredField && (index.h("div", { key: '3109f9ca0c4dbdfdde971b9c30c65e90a3d2c573', class: "required", "aria-hidden": "true" }, "*"))), index.h("div", { key: 'a3bfc9d17aa1df1ff84e807cd21bfb52dd3690de', class: `field-wrapper ${this.el.shadowRoot.activeElement === this.inputEl ? "focused" : ""} ${this.errorMessage ? "invalid" : ""}`, ref: (el) => (this.fieldWrapperEl = el) }, index.h("div", { key: 'be11a9727d97017988960d9458bf018e27f25c3b', class: "upper-row" }, index.h("div", { key: '9ae64eac0452889a0dbc49630a731f297c92c8c5', class: "svg-icon svg-search" }), index.h("div", { key: '07372a530d3bd24b8ae783d0bed5a3e095dbeeeb', class: `tags-and-input-wrapper` }, index.h("ul", { key: '2b16ed13429d52b1ad44b1aea45087f34e05997f', ref: (el) => (this.tagAreaEl = el), class: `tag-area ${this.taggedOptions.length === 0 && "empty"} ${this.isKeying ? "user-is-keying" : ""}`, role: "listbox", "aria-activedescendant": this.focusedTag ? this.focusedTag.id : null, "aria-orientation": "horizontal", "aria-labelledby": "sr-instructions", tabindex: this._tagEls.length > 0 ? 0 : -1, "aria-describedby": `info max-tags`, onFocus: (ev) => this.handleTagAreaFocus(ev), onBlur: (ev) => {
+        return (index.h("div", { key: 'dea9ac53c8001429751e759746085ebb7f9bcc98', class: `wrapper label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, index.h("div", { key: 'd3956d7ac5042bf4e0629173cebe2e46ea7e9a3b', class: "label-wrapper" }, index.h("label", { key: '83e407057a18e0e6d21af52a35e7c57af40bf147', class: "label", htmlFor: "input", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => functions.hideTooltip() }, this.label), this.labelPosition !== "none" && this.requiredField && (index.h("div", { key: '70d92671c54ad690834de1f6873aec20e5f4fd80', class: "required", "aria-hidden": "true" }, "*"))), index.h("div", { key: '79dba949ca7f4e73d8275e6e8c07e7737c4cef43', class: `field-wrapper ${this.el.shadowRoot.activeElement === this.inputEl ? "focused" : ""} ${this.errorMessage ? "invalid" : ""}`, ref: (el) => (this.fieldWrapperEl = el) }, index.h("div", { key: '24179f798549b936c2e2a90b43c377d5c7df155b', class: "upper-row" }, index.h("div", { key: '799d830b6ff63dec947f776cdcebce017f83f9bb', class: "svg-icon svg-search" }), index.h("div", { key: 'eb31ec918a327e87176db9bdda33e160eb40cf29', class: `tags-and-input-wrapper` }, index.h("ul", { key: 'cb5a56da3f08bac148853ec9e6bbf0f755cc8643', ref: (el) => (this.tagAreaEl = el), class: `tag-area ${this.taggedOptions.length === 0 && "empty"} ${this.isKeying ? "user-is-keying" : ""}`, role: "listbox", "aria-activedescendant": this.focusedTag ? this.focusedTag.id : null, "aria-orientation": "horizontal", "aria-labelledby": "sr-instructions", tabindex: this._tagEls.length > 0 ? 0 : -1, "aria-describedby": `info max-tags`, onFocus: (ev) => this.handleTagAreaFocus(ev), onBlur: (ev) => {
                 this.focusedTagIndex = undefined;
                 this.handleBlur(ev);
-            }, onKeyDown: (ev) => this.handleTagAreaKeyDown(ev) }, this.renderTags()), index.h("div", { key: '3888229daf857f5c86ee4112d0762b9be5b3b099', class: "sr-only", id: "sr-instructions" }, this.label, ". ", this.tagAreaInstructions), this.isDropdown && this.renderDropdownInput(), this.isTable && this.renderTableInput()), this.isDropdown && (index.h("div", { key: 'fce52fa11fb5403c1dd7ac9c2dca11bbe9402665', class: "character-count" }, this.charCount, "/", this.characterLimit))), this.renderTagCounter(), this.isDropdown && this.renderDropdown()), this.info && (index.h("div", { key: '1befdf76851f651878ade4110d8aec2e0238cdbe', id: "info", class: "info-text" }, this.info)), index.h("div", { key: '4bcd00c2fa6d4f00c79fc8a752a3dd57594ce9a1', id: "error" }, this.errorMessage), index.h("div", { key: '9d6da4e7accb62f9ad05dbdf0c5827ea18ade783', class: "sr-only", "aria-live": "polite", ref: (el) => (this.liveRegionEl = el), "aria-atomic": "true" }, this.liveRegionMessage), this.isTable && this.renderTable()));
+            }, onKeyDown: (ev) => this.handleTagAreaKeyDown(ev) }, this.renderTags()), index.h("div", { key: 'eb39838bb6fa30ed96864d605e58d8d28291bb09', class: "sr-only", id: "sr-instructions" }, this.label, ". ", this.tagAreaInstructions), this.isDropdown && this.renderDropdownInput(), this.isTable && this.renderTableInput()), this.isDropdown && (index.h("div", { key: '988f231710b140862bf4ff637611b3e7172e7e80', class: "character-count" }, this.charCount, "/", this.characterLimit))), this.renderTagCounter(), this.isDropdown && this.renderDropdown()), this.info && (index.h("div", { key: '6826b1f0620e14e7e921314085523cf1c3623164', id: "info", class: "info-text" }, this.info)), index.h("div", { key: '28632b831feb09801e7036f7b458303a5daee980', id: "error" }, this.errorMessage), index.h("div", { key: '339b33e97121b8abb5115e516e61a2fa56e4a34e', class: "sr-only", "aria-live": "polite", ref: (el) => (this.liveRegionEl = el), "aria-atomic": "true" }, this.liveRegionMessage), this.isTable && this.renderTable()));
     }
     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,35 @@ 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.
+ * - This component must be the header's true first child at its true leading edge, so don't
+ *   give the header uniform padding (or `padding-inline-start`) for breathing room — that
+ *   inset falls on this component the same way padding on its own host would. If the header
+ *   needs padding for its other content, use `padding-inline-end` instead.
+ * - 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 +82,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: '6f135919a43b55f7c4fca79d79e9a5c201d84fdd', class: `hamburger ${this.open ? "nav-open" : "nav-closed"}` }, h("button", { key: '8d930f77ea878a4f7757084fe45178004cc8a74e', "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: '798de550cd68d4d3b2ce78036206175e3901e1c0', 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-item.js

@@ -3,12 +3,30 @@ import { h, Host } from "@stencil/core";
  * A single navigation link inside a wm-navigation. Renders as an anchor element with an
  * optional icon slot. Always used as a direct child of wm-navigation.
  *
+ * @category Navigation
+ *
  * @slot - Optional icon element displayed before the link text.
  *
+ * @accessibility
+ * - Rendered with `role="listitem"`.
+ * - The icon slot's wrapper carries `aria-hidden="true"`, so whatever is slotted there (an
+ *   SVG, an icon-font element, an `<img>`) is already hidden from assistive tech — no need to
+ *   add `aria-hidden` to it yourself.
+ *
  * @usageNotes
  * - Set `active` on the item that corresponds to the current route.
  * - Clicking an item emits `wmNavigationItemClicked`, which the parent wm-navigation listens
  *   to in order to close the collapsible menu on narrow viewports.
+ * - Preferred, for an icon not already in Ripple's own set: an inline SVG referencing a shared
+ *   sprite — `<svg width="1.5rem" height="1.5rem"><use href="...#icon-id"
+ *   fill="currentColor"></use></svg>`. 24px (`1.5rem`) is the standard icon size for this slot.
+ *   `fill="currentColor"` must be set explicitly — omitting it renders a fixed black icon
+ *   instead of the active/hover color, since SVG's own default fill is black, not the
+ *   inherited text color.
+ * - Ripple's bundled icon set is also available for icons it already includes (the
+ *   `svg-icon svg-<name>` classes in Ripple's global styles). Avoid an icon font (e.g.
+ *   Material Design Icons) or an `<img>` — neither can pick up the active/hover recoloring
+ *   the way an SVG using `fill="currentColor"` can.
  *
  * @example {html} Basic navigation item
  * <wm-navigation-item href="/dashboard" text="Dashboard" active></wm-navigation-item>
@@ -18,12 +36,16 @@ import { h, Host } from "@stencil/core";
  *
  * @example {html} Navigation item with icon
  * <wm-navigation-item href="/reports" text="Reports">
- *   <span class="svg-icon svg-chart"></span>
+ *   <svg width="1.5rem" height="1.5rem">
+ *     <use href="/images/icons.svg#chart" fill="currentColor"></use>
+ *   </svg>
  * </wm-navigation-item>
  *
  * @example {react} Navigation item with icon
  * <WmNavigationItem href="/reports" text="Reports">
- *   <span className="svg-icon svg-chart" />
+ *   <svg width="1.5rem" height="1.5rem">
+ *     <use href="/images/icons.svg#chart" fill="currentColor" />
+ *   </svg>
  * </WmNavigationItem>
  */
 export class NavigationItem {
@@ -33,7 +55,7 @@ export class NavigationItem {
         this.active = undefined;
     }
     render() {
-        return (h(Host, { key: '5c37c39e27b4602bcc53f2a1e118fb427b7a9a1a', role: "listitem" }, h("a", { key: 'ba3e7216ba1a5e7cb8d61dff61b353eeaaddee34', class: `link ${this.active ? "active" : ""}`, href: this.href, onClick: () => this.wmNavigationItemClicked.emit() }, h("div", { key: '9a35a2bd7f3474a182e187f8fe4b35904cb00862', class: "icon", "aria-hidden": "true" }, h("slot", { key: 'fb6858dafb750fcee200e57757dd86bbfc05cd23' })), h("div", { key: '6b2c933f73fd07746c3f3bcb656f9fc9563e88cd', class: "text" }, this.text))));
+        return (h(Host, { key: 'bbe3c0a165b8d7d4bf036e5a80b23eb11446b90e', role: "listitem" }, h("a", { key: '7f4ef86559f368dca39bd7a72ed05daafb539648', class: `link ${this.active ? "active" : ""}`, href: this.href, onClick: () => this.wmNavigationItemClicked.emit() }, h("div", { key: '8ae1aae920abe64829e87f2a107f1bf3eb752e50', class: "icon", "aria-hidden": "true" }, h("slot", { key: '1da830a8aae16100d5c99b5bfe7e80086f8a7baa' })), h("div", { key: '876286ffd8f555d840538a088051faeede3882ae', class: "text" }, this.text))));
     }
     static get is() { return "wm-navigation-item"; }
     static get encapsulation() { return "shadow"; }

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

@@ -26,50 +26,111 @@ import { globalMessages } from "../../global/intl";
  *
  * @usageNotes
  * - 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, with room around it so it isn't flush
- *   against neighboring header content.
+ *   with wm-navigation via the `wmNavigationHamburgerClicked` window event, 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.
- * - Navigation and main content scroll independently — no additional overflow handling is needed.
+ * - wm-navigation-item accepts an icon in its default slot — see its own docs for the
+ *   preferred SVG-sprite pattern.
  *
  * 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. Without one, the navigation and content stack instead of sitting side by
- *   side as a sidebar on viewports 1024px and wider.
+ *   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 it and the wrapper just
+ *   grows to fit its tallest child, the whole document scrolls as one long page, and this
+ *   component's own item list loses its independent scroll too.
  *
  * @example {html} Basic navigation
- * <header class="app-header">
- *   <div class="app-header__hamburger">
+ * <style>
+ *   .app-shell {
+ *     display: flex;
+ *     flex-direction: column;
+ *     height: 100vh;
+ *   }
+ *   .app-header {
+ *     flex: 0 0 auto;
+ *     display: flex;
+ *     align-items: center;
+ *     padding-inline-end: 1.5rem;
+ *   }
+ *   .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>
- *   </div>
- *   <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>
+ *     <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>
+ *         <svg width="1.5rem" height="1.5rem">
+ *           <use href="/images/icons.svg#dashboard" fill="currentColor"></use>
+ *         </svg>
+ *       </wm-navigation-item>
+ *       <wm-navigation-item href="/reports" text="Reports">
+ *         <svg width="1.5rem" height="1.5rem">
+ *           <use href="/images/icons.svg#chart" fill="currentColor"></use>
+ *         </svg>
+ *       </wm-navigation-item>
+ *     </wm-navigation>
+ *     <div class="app-main__content">Page content</div>
+ *   </main>
+ * </div>
  *
  * @example {react} Basic navigation
- * <header className="app-header">
- *   <div className="app-header__hamburger">
+ * <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+ *   <header
+ *     className="app-header"
+ *     style={{ display: "flex", alignItems: "center", paddingInlineEnd: "1.5rem" }}
+ *   >
  *     <WmNavigationHamburger navId="main-nav" />
- *   </div>
- *   <a className="app-header__logo" href="/">App Name</a>
- * </header>
- * <main className="app-main">
- *   <WmNavigation id="main-nav">
- *     <WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
- *     <WmNavigationItem href="/reports" text="Reports" />
- *   </WmNavigation>
- *   <div className="app-main__content">Page content</div>
- * </main>
+ *     <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}>
+ *         <svg width="1.5rem" height="1.5rem">
+ *           <use href="/images/icons.svg#dashboard" fill="currentColor" />
+ *         </svg>
+ *       </WmNavigationItem>
+ *       <WmNavigationItem href="/reports" text="Reports">
+ *         <svg width="1.5rem" height="1.5rem">
+ *           <use href="/images/icons.svg#chart" fill="currentColor" />
+ *         </svg>
+ *       </WmNavigationItem>
+ *     </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
@@ -176,9 +237,9 @@ export class Navigation {
             } }));
     }
     render() {
-        return (h(Host, { key: '96933040f7f88edf4e52c5e0480712e1f15e8db6', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (h("div", { key: '4658a3e22aa96a55dfb5b0211912805b683e26d2', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), h("div", { key: 'cb3ae13600538706292ed27eeff3f70e33015975', class: "tray" }, h("div", { key: 'df934dfeb30d54294656dde2cfc78c95c6140e65', class: "toggle-wrapper" }, h("wm-button", { key: '478b6428b08703302a21f64d7adc58e6788e1803', 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: 'a15b95ca5769e6a996542f3fb0f1edf8928ed4ea', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (h("div", { key: 'add1bb58939e3d076c7890aa1cb3efd932f977dc', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), h("div", { key: '98491d3d97807417a13b677894ee452e89e9cea8', class: "tray" }, h("div", { key: 'cf058b8b33a07598f19318977e26e652304faf4f', class: "toggle-wrapper" }, h("wm-button", { key: '7e8d936e3fdc9c718bf9442b6840464a6caddcab', 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: '32035dea4487af347ec5e56c3010bdf8b84d2c12', class: "navlist" }, h("slot", { key: 'a3512e42e16da5ad5591fa1f1f5211dc5b1576ee' }))), this.isCollapsible && (h("div", { key: '8e77d6376ccc683560ec214d2ec7d694aa417789', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
+            } })), h("ul", { key: 'e90219ba02e6a2330095e12ee4793ac82100fc5d', class: "navlist" }, h("slot", { key: '83e672cf048480abbef358f8249cb1622e2fad3c' }))), this.isCollapsible && (h("div", { key: '3c16362bebb241d693aa6aa8fd7226a34039901d', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
     }
     static get is() { return "wm-navigation"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/wm-tag-input/wm-tag-input.js

@@ -434,7 +434,6 @@ export class TagInput {
         const addedNodes = Array.from(record.addedNodes);
         if (addedNodes.length > 0) {
             this.assignOptionIds();
-            // reassign rather than push: Stencil only re-renders on a state reference change
             const newNodes = addedNodes.filter((n) => !this.tagsList.includes(n));
             if (newNodes.length > 0) {
                 this.tagsList = [...this.tagsList, ...newNodes];
@@ -1077,10 +1076,10 @@ export class TagInput {
         }
     }
     render() {
-        return (h("div", { key: '0506ec7b7255034f0fa8132d813727a72895b86a', class: `wrapper label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: '8f8726c6d9e1a524b6c9b9aa90dee9748fc93635', class: "label-wrapper" }, h("label", { key: '1f9b00a496fcd9923800471cc77e8c9c65111a8b', class: "label", htmlFor: "input", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label), this.labelPosition !== "none" && this.requiredField && (h("div", { key: '3109f9ca0c4dbdfdde971b9c30c65e90a3d2c573', class: "required", "aria-hidden": "true" }, "*"))), h("div", { key: 'a3bfc9d17aa1df1ff84e807cd21bfb52dd3690de', class: `field-wrapper ${this.el.shadowRoot.activeElement === this.inputEl ? "focused" : ""} ${this.errorMessage ? "invalid" : ""}`, ref: (el) => (this.fieldWrapperEl = el) }, h("div", { key: 'be11a9727d97017988960d9458bf018e27f25c3b', class: "upper-row" }, h("div", { key: '9ae64eac0452889a0dbc49630a731f297c92c8c5', class: "svg-icon svg-search" }), h("div", { key: '07372a530d3bd24b8ae783d0bed5a3e095dbeeeb', class: `tags-and-input-wrapper` }, h("ul", { key: '2b16ed13429d52b1ad44b1aea45087f34e05997f', ref: (el) => (this.tagAreaEl = el), class: `tag-area ${this.taggedOptions.length === 0 && "empty"} ${this.isKeying ? "user-is-keying" : ""}`, role: "listbox", "aria-activedescendant": this.focusedTag ? this.focusedTag.id : null, "aria-orientation": "horizontal", "aria-labelledby": "sr-instructions", tabindex: this._tagEls.length > 0 ? 0 : -1, "aria-describedby": `info max-tags`, onFocus: (ev) => this.handleTagAreaFocus(ev), onBlur: (ev) => {
+        return (h("div", { key: 'dea9ac53c8001429751e759746085ebb7f9bcc98', class: `wrapper label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: 'd3956d7ac5042bf4e0629173cebe2e46ea7e9a3b', class: "label-wrapper" }, h("label", { key: '83e407057a18e0e6d21af52a35e7c57af40bf147', class: "label", htmlFor: "input", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label), this.labelPosition !== "none" && this.requiredField && (h("div", { key: '70d92671c54ad690834de1f6873aec20e5f4fd80', class: "required", "aria-hidden": "true" }, "*"))), h("div", { key: '79dba949ca7f4e73d8275e6e8c07e7737c4cef43', class: `field-wrapper ${this.el.shadowRoot.activeElement === this.inputEl ? "focused" : ""} ${this.errorMessage ? "invalid" : ""}`, ref: (el) => (this.fieldWrapperEl = el) }, h("div", { key: '24179f798549b936c2e2a90b43c377d5c7df155b', class: "upper-row" }, h("div", { key: '799d830b6ff63dec947f776cdcebce017f83f9bb', class: "svg-icon svg-search" }), h("div", { key: 'eb31ec918a327e87176db9bdda33e160eb40cf29', class: `tags-and-input-wrapper` }, h("ul", { key: 'cb5a56da3f08bac148853ec9e6bbf0f755cc8643', ref: (el) => (this.tagAreaEl = el), class: `tag-area ${this.taggedOptions.length === 0 && "empty"} ${this.isKeying ? "user-is-keying" : ""}`, role: "listbox", "aria-activedescendant": this.focusedTag ? this.focusedTag.id : null, "aria-orientation": "horizontal", "aria-labelledby": "sr-instructions", tabindex: this._tagEls.length > 0 ? 0 : -1, "aria-describedby": `info max-tags`, onFocus: (ev) => this.handleTagAreaFocus(ev), onBlur: (ev) => {
                 this.focusedTagIndex = undefined;
                 this.handleBlur(ev);
-            }, onKeyDown: (ev) => this.handleTagAreaKeyDown(ev) }, this.renderTags()), h("div", { key: '3888229daf857f5c86ee4112d0762b9be5b3b099', class: "sr-only", id: "sr-instructions" }, this.label, ". ", this.tagAreaInstructions), this.isDropdown && this.renderDropdownInput(), this.isTable && this.renderTableInput()), this.isDropdown && (h("div", { key: 'fce52fa11fb5403c1dd7ac9c2dca11bbe9402665', class: "character-count" }, this.charCount, "/", this.characterLimit))), this.renderTagCounter(), this.isDropdown && this.renderDropdown()), this.info && (h("div", { key: '1befdf76851f651878ade4110d8aec2e0238cdbe', id: "info", class: "info-text" }, this.info)), h("div", { key: '4bcd00c2fa6d4f00c79fc8a752a3dd57594ce9a1', id: "error" }, this.errorMessage), h("div", { key: '9d6da4e7accb62f9ad05dbdf0c5827ea18ade783', class: "sr-only", "aria-live": "polite", ref: (el) => (this.liveRegionEl = el), "aria-atomic": "true" }, this.liveRegionMessage), this.isTable && this.renderTable()));
+            }, onKeyDown: (ev) => this.handleTagAreaKeyDown(ev) }, this.renderTags()), h("div", { key: 'eb39838bb6fa30ed96864d605e58d8d28291bb09', class: "sr-only", id: "sr-instructions" }, this.label, ". ", this.tagAreaInstructions), this.isDropdown && this.renderDropdownInput(), this.isTable && this.renderTableInput()), this.isDropdown && (h("div", { key: '988f231710b140862bf4ff637611b3e7172e7e80', class: "character-count" }, this.charCount, "/", this.characterLimit))), this.renderTagCounter(), this.isDropdown && this.renderDropdown()), this.info && (h("div", { key: '6826b1f0620e14e7e921314085523cf1c3623164', id: "info", class: "info-text" }, this.info)), h("div", { key: '28632b831feb09801e7036f7b458303a5daee980', id: "error" }, this.errorMessage), h("div", { key: '339b33e97121b8abb5115e516e61a2fa56e4a34e', class: "sr-only", "aria-live": "polite", ref: (el) => (this.liveRegionEl = el), "aria-atomic": "true" }, this.liveRegionMessage), this.isTable && this.renderTable()));
     }
     static get is() { return "wm-tag-input"; }
     static get encapsulation() { return "shadow"; }

package/dist/docs/docs.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-09-08T13:22:53",
+  "timestamp": "2026-09-15T19:20:00",
   "compiler": {
     "name": "@stencil/core",
     "version": "4.21.0",
@@ -7683,15 +7683,15 @@
         },
         {
           "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 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, with room around it so it isn't flush\n  against neighboring header content.\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.\n- Give the element that wraps wm-navigation and the page content (commonly `<main>`) a flex\n  or grid layout. Without one, the navigation and content stack instead of sitting side by\n  side as a sidebar on viewports 1024px and wider."
+          "text": "- Use `wm-navigation-hamburger` (a separate component) as the external toggle. It communicates\n  with wm-navigation via the `wmNavigationHamburgerClicked` window event, so it does not need\n  to be a DOM sibling of wm-navigation — place it in the page header instead, at the leading\n  edge before the logo. It already reserves its own touch-target padding on narrower\n  viewports, so don't add further leading margin or padding on the host for that — but the\n  gap between it and the logo is still the header's own layout to provide; the hamburger's\n  box reserves no trailing space of its own (see wm-navigation-hamburger's docs).\n- `open` can be set initially to `true` to start the navigation expanded.\n- wm-navigation-item accepts an icon in its default slot — see its own docs for the\n  preferred SVG-sprite pattern.\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 it and the wrapper just\n  grows to fit its tallest child, the whole document scrolls as one long page, and this\n  component's own item list loses its independent scroll too."
         },
         {
           "name": "example",
-          "text": "{html} Basic navigation\n<header class=\"app-header\">\n<div class=\"app-header__hamburger\">\n<wm-navigation-hamburger nav-id=\"main-nav\"></wm-navigation-hamburger>\n</div>\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>"
+          "text": "{html} Basic navigation\n<style>\n.app-shell {\ndisplay: flex;\nflex-direction: column;\nheight: 100vh;\n}\n.app-header {\nflex: 0 0 auto;\ndisplay: flex;\nalign-items: center;\npadding-inline-end: 1.5rem;\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>\n<svg width=\"1.5rem\" height=\"1.5rem\">\n <use href=\"/images/icons.svg#dashboard\" fill=\"currentColor\"></use>\n</svg>\n</wm-navigation-item>\n<wm-navigation-item href=\"/reports\" text=\"Reports\">\n<svg width=\"1.5rem\" height=\"1.5rem\">\n <use href=\"/images/icons.svg#chart\" fill=\"currentColor\"></use>\n</svg>\n</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<header className=\"app-header\">\n<div className=\"app-header__hamburger\">\n<WmNavigationHamburger navId=\"main-nav\" />\n</div>\n<a className=\"app-header__logo\" href=\"/\">App Name</a>\n</header>\n<main className=\"app-main\">\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\">Page content</div>\n</main>"
+          "text": "{react} Basic navigation\n<div style={{ display: \"flex\", flexDirection: \"column\", height: \"100vh\" }}>\n<header\nclassName=\"app-header\"\nstyle={{ display: \"flex\", alignItems: \"center\", paddingInlineEnd: \"1.5rem\" }}\n>\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<svg width=\"1.5rem\" height=\"1.5rem\">\n <use href=\"/images/icons.svg#dashboard\" fill=\"currentColor\" />\n</svg>\n</WmNavigationItem>\n<WmNavigationItem href=\"/reports\" text=\"Reports\">\n<svg width=\"1.5rem\" height=\"1.5rem\">\n <use href=\"/images/icons.svg#chart\" fill=\"currentColor\" />\n</svg>\n</WmNavigationItem>\n</WmNavigation>\n<div className=\"app-main__content\" style={{ overflowY: \"auto\", minHeight: 0 }}>\nPage content\n</div>\n</main>\n</div>"
         },
         {
           "name": "requiredSetup",
@@ -7800,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."
@@ -7812,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- This component must be the header's true first child at its true leading edge, so don't\n  give the header uniform padding (or `padding-inline-start`) for breathing room — that\n  inset falls on this component the same way padding on its own host would. If the header\n  needs padding for its other content, use `padding-inline-end` instead.\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": {},
@@ -7913,13 +7921,21 @@
       "tag": "wm-navigation-item",
       "docs": "A single navigation link inside a wm-navigation. Renders as an anchor element with an\noptional icon slot. Always used as a direct child of wm-navigation.",
       "docsTags": [
+        {
+          "name": "category",
+          "text": "Navigation"
+        },
         {
           "name": "slot",
           "text": "- Optional icon element displayed before the link text."
         },
+        {
+          "name": "accessibility",
+          "text": "- Rendered with `role=\"listitem\"`.\n- The icon slot's wrapper carries `aria-hidden=\"true\"`, so whatever is slotted there (an\n  SVG, an icon-font element, an `<img>`) is already hidden from assistive tech — no need to\n  add `aria-hidden` to it yourself."
+        },
         {
           "name": "usageNotes",
-          "text": "- Set `active` on the item that corresponds to the current route.\n- Clicking an item emits `wmNavigationItemClicked`, which the parent wm-navigation listens\n  to in order to close the collapsible menu on narrow viewports."
+          "text": "- Set `active` on the item that corresponds to the current route.\n- Clicking an item emits `wmNavigationItemClicked`, which the parent wm-navigation listens\n  to in order to close the collapsible menu on narrow viewports.\n- Preferred, for an icon not already in Ripple's own set: an inline SVG referencing a shared\n  sprite — `<svg width=\"1.5rem\" height=\"1.5rem\"><use href=\"...#icon-id\"\n  fill=\"currentColor\"></use></svg>`. 24px (`1.5rem`) is the standard icon size for this slot.\n  `fill=\"currentColor\"` must be set explicitly — omitting it renders a fixed black icon\n  instead of the active/hover color, since SVG's own default fill is black, not the\n  inherited text color.\n- Ripple's bundled icon set is also available for icons it already includes (the\n  `svg-icon svg-<name>` classes in Ripple's global styles). Avoid an icon font (e.g.\n  Material Design Icons) or an `<img>` — neither can pick up the active/hover recoloring\n  the way an SVG using `fill=\"currentColor\"` can."
         },
         {
           "name": "example",
@@ -7931,11 +7947,11 @@
         },
         {
           "name": "example",
-          "text": "{html} Navigation item with icon\n<wm-navigation-item href=\"/reports\" text=\"Reports\">\n<span class=\"svg-icon svg-chart\"></span>\n</wm-navigation-item>"
+          "text": "{html} Navigation item with icon\n<wm-navigation-item href=\"/reports\" text=\"Reports\">\n<svg width=\"1.5rem\" height=\"1.5rem\">\n<use href=\"/images/icons.svg#chart\" fill=\"currentColor\"></use>\n</svg>\n</wm-navigation-item>"
         },
         {
           "name": "example",
-          "text": "{react} Navigation item with icon\n<WmNavigationItem href=\"/reports\" text=\"Reports\">\n<span className=\"svg-icon svg-chart\" />\n</WmNavigationItem>"
+          "text": "{react} Navigation item with icon\n<WmNavigationItem href=\"/reports\" text=\"Reports\">\n<svg width=\"1.5rem\" height=\"1.5rem\">\n<use href=\"/images/icons.svg#chart\" fill=\"currentColor\" />\n</svg>\n</WmNavigationItem>"
         }
       ],
       "usage": {},

package/dist/docs/props-reference.json

@@ -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,8 @@
 | **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 |
+| **Navigation Item** | `wm-navigation-item` | `wm-navigation-item.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 |