@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

@@ -1,5 +1,97 @@
 import { h } from "@stencil/core";
 import { generateId } from "../../global/functions";
+/**
+ * Modal dialog that overlays the page. Renders as a full-bleed `modal` (default) or a
+ * smaller centered `dialog`. Content is provided through wm-modal-header, wm-modal-footer,
+ * and arbitrary slotted children.
+ *
+ * @slot - Modal content: wm-modal-header, body content, and wm-modal-footer.
+ *
+ * @keyboardInteraction
+ * - **Tab**: Advances focus through focusable elements; wraps from the last element back to the first.
+ * - **Shift+Tab**: Moves focus backward; wraps from the first element to the last.
+ * - **Escape**: Fires `wmModalCloseTriggered` (the host application must set `open = false` on the element ref in response).
+ * - **Enter / Space**: Activates the focused button.
+ *
+ * @accessibility
+ * - Rendered as a `<dialog>` element with `aria-labelledby` pointing to the heading.
+ * - When footer buttons receive initial focus (`element-to-focus="primary"` or `"secondary"`),
+ *   the element `id` on `<wm-modal>` is required — it is used to construct `aria-describedby`
+ *   relationships between the heading, content, and footer.
+ * - The content wrapper must have `id="content-[id of wm-modal]"` for the aria-describedby association.
+ * - Focus returns automatically to the element that was active when the modal opened.
+ *
+ * @usageNotes
+ * - Always render the component and toggle `open` — do not conditionally mount/unmount it.
+ *   Conditional rendering breaks the `aria-live` region detection and can cause body-scroll issues.
+ * - In React, set `open` imperatively via a ref (`ref.current.open = true/false`) rather than
+ *   passing it as a prop. Using the prop triggers a React re-render that interferes with the
+ *   native `<dialog>` focus-return mechanism and causes `:focus-visible` styles to appear on
+ *   the trigger element after close.
+ * - For scrollable modal content, set `overflow: auto` on the content wrapper and reset
+ *   `scrollTop` when reopening a previously scrolled modal.
+ * - On mobile (<768px) with `modal-type="dialog"`, `element-to-focus` targeting a footer button
+ *   is overridden to the close button to avoid disorienting scroll behavior.
+ *
+ * @example {html} Basic modal
+ * <wm-modal id="confirm-modal" open>
+ *   <wm-modal-header heading="Confirm action"></wm-modal-header>
+ *   <div id="content-confirm-modal">Are you sure you want to continue?</div>
+ *   <wm-modal-footer primary-text="Confirm" secondary-text="Cancel"></wm-modal-footer>
+ * </wm-modal>
+ *
+ * @example {react} Basic modal
+ * // Set open imperatively via ref -- do not use open={} as a React prop.
+ * // This preserves the native <dialog> focus-return without triggering :focus-visible.
+ * const modalRef = useRef(null);
+ *
+ * const openModal = () => { modalRef.current.open = true; };
+ * const closeModal = () => { modalRef.current.open = false; };
+ *
+ * <WmButton onWmButtonClicked={openModal}>Open modal</WmButton>
+ *
+ * <WmModal
+ *   ref={modalRef}
+ *   id="confirm-modal"
+ *   onWmModalCloseTriggered={closeModal}
+ *   onWmModalPrimaryTriggered={closeModal}
+ *   onWmModalSecondaryTriggered={closeModal}
+ * >
+ *   <WmModalHeader heading="Confirm action" />
+ *   <div id="content-confirm-modal">Are you sure you want to continue?</div>
+ *   <WmModalFooter primaryText="Confirm" secondaryText="Cancel" />
+ * </WmModal>
+ *
+ * @example {html} Dialog type (smaller, centered)
+ * <wm-modal id="info-dialog" modal-type="dialog" open>
+ *   <wm-modal-header heading="Information"></wm-modal-header>
+ *   <div id="content-info-dialog">This is additional context.</div>
+ *   <wm-modal-footer primary-text="Got it"></wm-modal-footer>
+ * </wm-modal>
+ *
+ * @example {react} Dialog type
+ * const dialogRef = useRef(null);
+ *
+ * const openDialog = () => { dialogRef.current.open = true; };
+ * const closeDialog = () => { dialogRef.current.open = false; };
+ *
+ * <WmButton onWmButtonClicked={openDialog}>Open dialog</WmButton>
+ *
+ * <WmModal
+ *   ref={dialogRef}
+ *   id="info-dialog"
+ *   modalType="dialog"
+ *   onWmModalCloseTriggered={closeDialog}
+ *   onWmModalPrimaryTriggered={closeDialog}
+ * >
+ *   <WmModalHeader heading="Information" />
+ *   <div id="content-info-dialog">This is additional context.</div>
+ *   <WmModalFooter primaryText="Got it" />
+ * </WmModal>
+ *
+ * @category Communication
+ * @displayName Modal & Dialog
+ */
 export class Modal {
     constructor() {
         this.open = false;
@@ -90,12 +182,27 @@ export class Modal {
         }
         this.dialogEl.addEventListener("close", () => this.handleDialogClose());
     }
+    /**
+     * @description Programmatically fires `wmModalCloseTriggered`. Use when you need to trigger
+     * a close from outside the modal without simulating a button click.
+     * @returns A promise that resolves once the event has been emitted.
+     */
     async emitCloseEvent() {
         this.wmModalCloseTriggered.emit();
     }
+    /**
+     * @description Programmatically fires `wmModalPrimaryTriggered`. Use when you need to trigger
+     * the primary action from outside the modal.
+     * @returns A promise that resolves once the event has been emitted.
+     */
     async emitPrimaryEvent() {
         this.wmModalPrimaryTriggered.emit();
     }
+    /**
+     * @description Programmatically fires `wmModalSecondaryTriggered`. Use when you need to trigger
+     * the secondary action from outside the modal.
+     * @returns A promise that resolves once the event has been emitted.
+     */
     async emitSecondaryEvent() {
         this.wmModalSecondaryTriggered.emit();
     }
@@ -114,11 +221,11 @@ export class Modal {
         }
     }
     render() {
-        return (h("dialog", { key: '6146ea9b86156f864e74e1329db5ff68ea725790', class: `${"wm-" + this.modalType}`, "aria-labelledby": `wm-modal-heading-text-${this.uid}`, ref: (el) => (this.dialogEl = el), onKeyDown: (ev) => this.handleKeyDown(ev) }, h("div", { key: '30f644962a0cb1b84eab05b334548f8ba5bad563', class: "tabtrap sr-only", tabindex: "0", onFocus: (ev) => {
+        return (h("dialog", { key: '76ff8c280ec92ae62a2ad7be1cef0ca4b5825a8a', class: `${"wm-" + this.modalType}`, "aria-labelledby": `wm-modal-heading-text-${this.uid}`, ref: (el) => (this.dialogEl = el), onKeyDown: (ev) => this.handleKeyDown(ev) }, h("div", { key: '7e5c8cfcd4b4142ad9613e6c95ab1ee30b8d3983', class: "tabtrap sr-only", tabindex: "0", onFocus: (ev) => {
                 const focusedFromCloseButton = ev.relatedTarget && ev.relatedTarget == this.closeButtonEl;
                 // no related target means we're coming from outside the page (browser chrome), and first element should be focused instead
                 focusedFromCloseButton ? this.focusLastElement.emit() : this.focusFirstElement.emit();
-            } }), !this.hasBrowserPopoverSupport && h("div", { key: '6adb6d32c0e2a6f40b0925be7135befe886e1656', class: "wm-tooltip" }), h("slot", { key: 'f3f7f22e4a59aa9477c2e93b8775b1e15c6d0340' }), h("div", { key: 'c77444dcd4f59ef2bc235821aa26615520fdb0fa', class: "tabtrap sr-only", tabindex: "0", onFocus: () => {
+            } }), !this.hasBrowserPopoverSupport && h("div", { key: 'ddcc34184581a5c5706c906cfc29ee993db2ad0a', class: "wm-tooltip" }), h("slot", { key: 'e58b8aa324444208bf8ebf1d014bd22512b8dd4f' }), h("div", { key: '0b9e32ac74195ba449dd001890a8d163d36e5e85', class: "tabtrap sr-only", tabindex: "0", onFocus: () => {
                 this.focusFirstElement.emit();
             } })));
     }
@@ -146,7 +253,13 @@ export class Modal {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Controls the open/closed state of the modal. Always render the component and\ntoggle this prop \u2014 do not conditionally mount/unmount."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "open",
@@ -164,7 +277,13 @@ export class Modal {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Element to focus when the modal opens. Pass `\"primary\"` or `\"secondary\"` to\nfocus the corresponding wm-modal-footer button, or an element `id` to focus a specific\nelement in the modal body. Defaults to the close button. Requires `id` to be set on\n`<wm-modal>` when targeting footer buttons."
+                        }, {
+                            "name": "default",
+                            "text": "\"\""
+                        }],
                     "text": ""
                 },
                 "attribute": "element-to-focus",
@@ -182,7 +301,13 @@ export class Modal {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visual presentation style. `'modal'` renders a full-bleed overlay; `'dialog'`\nrenders a smaller centered panel."
+                        }, {
+                            "name": "default",
+                            "text": "\"modal\""
+                        }],
                     "text": ""
                 },
                 "attribute": "modal-type",
@@ -200,7 +325,10 @@ export class Modal {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Unique identifier used internally to wire `aria-labelledby` and\n`aria-describedby` relationships. Set automatically from the element's `id` attribute or\ngenerated if absent \u2014 do not set this prop manually."
+                        }],
                     "text": ""
                 },
                 "attribute": "uid",
@@ -221,7 +349,13 @@ export class Modal {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal tab-trap signals \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -236,7 +370,13 @@ export class Modal {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal tab-trap signals \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -251,7 +391,10 @@ export class Modal {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the close button is clicked or Escape is pressed. Does not bubble,\npreventing nested modals from closing simultaneously. The host application must set `open`\nto false in response."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -266,7 +409,10 @@ export class Modal {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the wm-modal-footer primary button is clicked."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -281,7 +427,10 @@ export class Modal {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the wm-modal-footer secondary button is clicked."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -307,7 +456,13 @@ export class Modal {
                 },
                 "docs": {
                     "text": "",
-                    "tags": []
+                    "tags": [{
+                            "name": "description",
+                            "text": "Programmatically fires `wmModalCloseTriggered`. Use when you need to trigger\na close from outside the modal without simulating a button click."
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves once the event has been emitted."
+                        }]
                 }
             },
             "emitPrimaryEvent": {
@@ -324,7 +479,13 @@ export class Modal {
                 },
                 "docs": {
                     "text": "",
-                    "tags": []
+                    "tags": [{
+                            "name": "description",
+                            "text": "Programmatically fires `wmModalPrimaryTriggered`. Use when you need to trigger\nthe primary action from outside the modal."
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves once the event has been emitted."
+                        }]
                 }
             },
             "emitSecondaryEvent": {
@@ -341,7 +502,13 @@ export class Modal {
                 },
                 "docs": {
                     "text": "",
-                    "tags": []
+                    "tags": [{
+                            "name": "description",
+                            "text": "Programmatically fires `wmModalSecondaryTriggered`. Use when you need to trigger\nthe secondary action from outside the modal."
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves once the event has been emitted."
+                        }]
                 }
             }
         };

package/dist/collection/components/wm-modal-pss/wm-modal-pss-footer.js

@@ -1,4 +1,8 @@
 import { h } from "@stencil/core";
+/**
+ * @internal
+ * @description Footer section for a wm-modal-pss. Not to be used outside of PSS.
+ */
 export class ModalPssFooter {
     constructor() {
         this.secondaryText = "";
@@ -27,7 +31,7 @@ export class ModalPssFooter {
         parentModal.emitSecondaryEvent();
     }
     render() {
-        return (h("div", { key: '2bd45880c74b9cb8c470a2983bf1d46b9acb61a5', class: `wm-wrapper ${this.infoText ? " footer-text" : ""}` }, h("div", { key: 'ce2d231765d334b03d6db9753591e72abf7efe9d', class: "wm-info", "aria-live": "polite" }, this.infoText), h("div", { key: '87a85ac4aa5514082c701111a9ec850d71034236', class: "wm-button-collection" }, this.secondaryText && (h("wm-button", { key: 'fbf829d3fa6ddda8fd8e20a402089258a9065836', onClick: () => this.emitParentSecondaryEvent(), id: `wm-secondary-${this.uid}`, ref: (el) => (this.primaryActionDisabled ? (this.lastElement = el) : null) }, this.secondaryText)), h("wm-button", { key: '06ec8889dcbe183da08c77d35a9a0d37be53510d', "button-type": this.deleteStyle ? "secondary" : "primary", "permanently-delete": this.deleteStyle, onClick: () => this.emitParentPrimaryEvent(), disabled: this.primaryActionDisabled, id: `wm-primary-${this.uid}`, ref: (el) => (!this.primaryActionDisabled ? (this.lastElement = el) : null) }, this.primaryText))));
+        return (h("div", { key: 'a52ef670cf97eb4d152898d0893d7980a3017ae8', class: `wm-wrapper ${this.infoText ? " footer-text" : ""}` }, h("div", { key: '14761e4c8b346aa64ab3fcda9c30732a3f18f3bc', class: "wm-info", "aria-live": "polite" }, this.infoText), h("div", { key: 'fb7411b87b34a4ff4081cda0520c14bd598e5333', class: "wm-button-collection" }, this.secondaryText && (h("wm-button", { key: 'af1a0e8a1ce71735c252a8700f334b4b05ec8811', onClick: () => this.emitParentSecondaryEvent(), id: `wm-secondary-${this.uid}`, ref: (el) => (this.primaryActionDisabled ? (this.lastElement = el) : null) }, this.secondaryText)), h("wm-button", { key: '55a18c788134ad22b90ec05ba8ab365b37649358', "button-type": this.deleteStyle ? "secondary" : "primary", "permanently-delete": this.deleteStyle, onClick: () => this.emitParentPrimaryEvent(), disabled: this.primaryActionDisabled, id: `wm-primary-${this.uid}`, ref: (el) => (!this.primaryActionDisabled ? (this.lastElement = el) : null) }, this.primaryText))));
     }
     static get is() { return "wm-modal-pss-footer"; }
     static get originalStyleUrls() {

package/dist/collection/components/wm-modal-pss/wm-modal-pss-header.js

@@ -1,5 +1,9 @@
 import { h, Host } from "@stencil/core";
 import { globalMessages } from "../../global/intl";
+/**
+ * @internal
+ * @description Header section for a wm-modal-pss. Not to be used outside of PSS.
+ */
 export class ModalPssHeader {
     constructor() {
         this.heading = "";
@@ -25,7 +29,7 @@ export class ModalPssHeader {
     //   this.headingElement.focus();
     // }
     render() {
-        return (h(Host, { key: '8de5b12e5695d10dd613903f686539d743659fe9' }, h("div", { key: '64316a6b7e6f254013e99d19f805e2cd9cdd5fa9', class: "wm-wrapper" }, h("div", { key: '24d7e5322e51a03af815ca52d96f97fcc3c248ab' }, h("h2", { key: '77be37c5914b42f32d84c69c1a7129c77612a380', class: "title", id: `wm-modal-heading-text-${this.uid}` }, this.heading, h("span", { key: '17b87f65f5ef154dd04f4e814b54db3c9fefb5c2', class: "subtitle" }, this.subheading))), h("wm-button", { key: 'cb32d3986b79bc75e14ae4cddaa96e8728117e29', "button-type": "navigational", icon: "f156", tooltip: globalMessages.close, "tooltip-position": "left", id: `wm-modal-close-${this.uid}`, ref: (el) => (this.closeButtonEl = el), onClick: () => this.emitParentCloseEvent() }))));
+        return (h(Host, { key: '04ee8b4b40cd449def589f8b7a3af74289273d2d' }, h("div", { key: '718fbd4188d2bfe7a671d548b149569c5bc28c21', class: "wm-wrapper" }, h("div", { key: '659db3df52655116df6adc60ead894f3bd815dc5' }, h("h2", { key: 'a7e11a02093e20fa6103cbe03a8dd1c8d6187245', class: "title", id: `wm-modal-heading-text-${this.uid}` }, this.heading, h("span", { key: 'c3f7e5923f6b161fd8b416050957b262e8539cd2', class: "subtitle" }, this.subheading))), h("wm-button", { key: '9fc53ae559afdf78354e6831e71e86517f726a71', "button-type": "navigational", icon: "f156", tooltip: globalMessages.close, "tooltip-position": "left", id: `wm-modal-close-${this.uid}`, ref: (el) => (this.closeButtonEl = el), onClick: () => this.emitParentCloseEvent() }))));
     }
     static get is() { return "wm-modal-pss-header"; }
     static get originalStyleUrls() {

package/dist/collection/components/wm-modal-pss/wm-modal-pss.js

@@ -1,6 +1,10 @@
 import { h, Host } from "@stencil/core";
 import { checkForActiveElInShadow } from "../../global/functions";
 import { generateId } from "../../global/functions";
+/**
+ * @internal
+ * @description Modal component created specifically for Planning and Self Studies. Not to be used outside of PSS.
+ */
 export class ModalPss {
     constructor() {
         this.bodyFocusListener = () => this.redirectFocusFromBody();
@@ -115,9 +119,9 @@ export class ModalPss {
         }
     }
     render() {
-        return (h(Host, { key: 'f88b5818e0bbd04790ebd3d2ad5ed7365cb4378e', class: `${this.open ? "" : "hide "}${"wm-" + this.modalType}`, role: "dialog", "aria-describedby": `wm-modal-heading-text-${this.uid}`, "aria-modal": "true", tabindex: this.open ? 0 : null, onFocus: () => {
+        return (h(Host, { key: 'aa75d1fe486eb78c8a8f8a7981358ef957f96604', class: `${this.open ? "" : "hide "}${"wm-" + this.modalType}`, role: "dialog", "aria-describedby": `wm-modal-heading-text-${this.uid}`, "aria-modal": "true", tabindex: this.open ? 0 : null, onFocus: () => {
                 this.focusLastElement.emit();
-            } }, h("div", { key: '716de7445a0492ff71faf681d58beb801eb985d4', class: "overlay", ref: (el) => (this.overlayEl = el) }), h("div", { key: '311087d52cee10763ed87f5532559dc7fc620a26', class: "sr-only", tabIndex: 0, onFocus: () => {
+            } }, h("div", { key: '9261a0354ae19956d46d816532c487302cfd2883', class: "overlay", ref: (el) => (this.overlayEl = el) }), h("div", { key: 'f746291ba0e49265e418efc506aa023b55c28dfc', class: "sr-only", tabIndex: 0, onFocus: () => {
                 this.focusFirstElement.emit();
             } })));
     }

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

@@ -1,5 +1,30 @@
 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.
+ *
+ * @keyboardInteraction
+ * - **Enter / Space**: Toggles the navigation open/closed.
+ *
+ * @accessibility
+ * - Rendered as a `<button>` with `aria-expanded` reflecting the navigation's open state.
+ * - Keeps `aria-expanded` in sync by listening to `wmNavigationStateChanged` from the
+ *   associated wm-navigation element.
+ *
+ * @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.
+ *
+ * @example {html} Basic hamburger
+ * <wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
+ * <wm-navigation id="main-nav">...</wm-navigation>
+ *
+ * @example {react} Basic hamburger
+ * <WmNavigationHamburger navId="main-nav" />
+ * <WmNavigation id="main-nav">...</WmNavigation>
+ */
 export class NavigationHamburger {
     constructor() {
         this.showNavMessage = intl.formatMessage({
@@ -34,7 +59,7 @@ export class NavigationHamburger {
         this.wmNavigationHamburgerClicked.emit();
     }
     render() {
-        return (h(Host, { key: 'e5fb73423c0af009ee5408853227f9cbd27d0a58', class: `hamburger ${this.open ? "nav-open" : "nav-closed"}` }, h("button", { key: 'c07546a67d2e470b7172485f02f2897af6730745', "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: 'a3ae264912ba81685737ee0f15459a21342b128c', class: "svg-icon svg-menu" }))));
+        return (h(Host, { key: 'df69ca361664452da552f6f401df3b541e82d112', class: `hamburger ${this.open ? "nav-open" : "nav-closed"}` }, h("button", { key: '34e5d08cdf3a131d94e25a6b25e1278ed4988a56', "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: '356150524abde1f09b453d4f9fa83c202588a534', class: "svg-icon svg-menu" }))));
     }
     static get is() { return "wm-navigation-hamburger"; }
     static get encapsulation() { return "shadow"; }
@@ -62,7 +87,13 @@ export class NavigationHamburger {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The `id` of the associated wm-navigation element. Required for semantic\nlinking and for keeping `aria-expanded` in sync with the navigation's open state."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "nav-id",
@@ -84,7 +115,10 @@ export class NavigationHamburger {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the button is clicked. Consumed by the associated wm-navigation\nto toggle its `open` state \u2014 not intended for direct application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {

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

@@ -1,4 +1,31 @@
 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.
+ *
+ * @slot - Optional icon element displayed before the link text.
+ *
+ * @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.
+ *
+ * @example {html} Basic navigation item
+ * <wm-navigation-item href="/dashboard" text="Dashboard" active></wm-navigation-item>
+ *
+ * @example {react} Basic navigation item
+ * <WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
+ *
+ * @example {html} Navigation item with icon
+ * <wm-navigation-item href="/reports" text="Reports">
+ *   <span class="svg-icon svg-chart"></span>
+ * </wm-navigation-item>
+ *
+ * @example {react} Navigation item with icon
+ * <WmNavigationItem href="/reports" text="Reports">
+ *   <span className="svg-icon svg-chart" />
+ * </WmNavigationItem>
+ */
 export class NavigationItem {
     constructor() {
         this.href = undefined;
@@ -6,7 +33,7 @@ export class NavigationItem {
         this.active = undefined;
     }
     render() {
-        return (h(Host, { key: 'cae324324ba502c4e438ed7d95d05b03c6e0abc8', role: "listitem" }, h("a", { key: '357321484d6f9ca76ae76588de0e0245bc429278', class: `link ${this.active ? "active" : ""}`, href: this.href, onClick: () => this.wmNavigationItemClicked.emit() }, h("div", { key: '0c12bdfbb8db550d99cee869e6238bc2f842753f', class: "icon", "aria-hidden": "true" }, h("slot", { key: 'ddd837246f782f9222e0f30d03a18e42d35221fa' })), h("div", { key: 'ca3a038c1b8c4e073fedb84f23a996c1e4556b59', class: "text" }, this.text))));
+        return (h(Host, { key: 'a6c1d9806c0da87d12dad513c5137e7a2186d749', role: "listitem" }, h("a", { key: '0d8f022c002d086158f27d3edbdf114c5e9087ba', class: `link ${this.active ? "active" : ""}`, href: this.href, onClick: () => this.wmNavigationItemClicked.emit() }, h("div", { key: '39e7641878440f468c447a755628965ce9268a22', class: "icon", "aria-hidden": "true" }, h("slot", { key: 'b09705b9625d7e8b43232345741c3eca0738650f' })), h("div", { key: '24e76eaae0dbfb701d08770ad0f645812419ac02', class: "text" }, this.text))));
     }
     static get is() { return "wm-navigation-item"; }
     static get encapsulation() { return "shadow"; }
@@ -34,7 +61,10 @@ export class NavigationItem {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "URL the link navigates to."
+                        }],
                     "text": ""
                 },
                 "attribute": "href",
@@ -51,7 +81,10 @@ export class NavigationItem {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The visible label text for the navigation link."
+                        }],
                     "text": ""
                 },
                 "attribute": "text",
@@ -68,7 +101,13 @@ export class NavigationItem {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Marks this item as the currently active route, applying active styling."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "active",
@@ -84,7 +123,10 @@ export class NavigationItem {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the link is clicked. Consumed by the parent wm-navigation to\nclose the collapsible menu on narrow viewports."
+                        }],
                     "text": ""
                 },
                 "complexType": {

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

@@ -1,6 +1,47 @@
 import { h, Host, forceUpdate } from "@stencil/core";
 import { intl, throttle } from "../../global/functions";
 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>`.
+ *
+ * @slot - One or more wm-navigation-item elements.
+ *
+ * @keyboardInteraction
+ * - **Escape**: Collapses the navigation when in collapsible mode.
+ * - **Tab / Shift+Tab**: Cycles through navigation items; focus is trapped within the component
+ *   while the collapsible menu is open.
+ * - **Enter / Space**: Activates the close button when focused (collapses the menu).
+ *
+ * @accessibility
+ * - Rendered with `role="navigation"` and an `aria-label` of "Main".
+ * - `aria-expanded` is set on the host element in collapsible mode only; omitted on wider viewports.
+ * - When the collapsible menu is open, focus is trapped and redirected back from the browser
+ *   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.
+ *
+ * @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>
+ *
+ * @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>
+ *
+ * @category Navigation
+ */
 export class Navigation {
     constructor() {
         this.mainNavigationMessage = intl.formatMessage({
@@ -96,9 +137,9 @@ export class Navigation {
             } }));
     }
     render() {
-        return (h(Host, { key: '728e290bb93236f900b6cee0ab9a7a864bd514cf', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (h("div", { key: '3997c9b2967adc85b41afc834bcbbe3f4e5c8067', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), h("div", { key: '960c41a5a0932757de5321ab2e21fe0dbad50f6e', class: "tray" }, h("div", { key: '6aaf6d8d88dbd243c0b84f11ce24d7f0202c6a70', class: "toggle-wrapper" }, h("wm-button", { key: 'e009a82b20fcd5ee7f7d045ba85e1a8265273f65', 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: '7ce2ecc617d551f0cb7223c261d67ba77ffc94a3', role: "navigation", "aria-expanded": this.ariaExpanded, "aria-label": this.mainNavigationMessage }, this.open ? this.renderOverlay() : "", this.isCollapsible && (h("div", { key: 'b1cf578c11f6b77ab8b2941eacaddbf067e8c41f', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.focusLastItem() })), h("div", { key: 'd659f52712bf5086105db9dee561974439c2196f', class: "tray" }, h("div", { key: 'f8ab74aee8ef40588e8e1a581b1a2a398b236c67', class: "toggle-wrapper" }, h("wm-button", { key: '585f5cc59d58477daba2645d10b96706151c3a46', 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: 'abf01dbc15485f42dfc2fa5c8f87a895d4451c8e', class: "navlist" }, h("slot", { key: 'cc42697807c886c6fbec7b1b446206caa41b34e7' }))), this.isCollapsible && (h("div", { key: '020a258359a5f27cc62a44fb229735ed752eae83', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
+            } })), h("ul", { key: 'c1bbc03cb4157c9b5a1713a5556438952aa140fa', class: "navlist" }, h("slot", { key: '3175962a28ac681dfe5cd6bb6f05f448641b4f1c' }))), this.isCollapsible && (h("div", { key: '21f7d9c75610ca8d590467a7f7eda4c6e29140e1', class: "trapfocus", tabindex: this.open ? 0 : undefined, onFocus: () => this.toggleEl.focus() }))));
     }
     static get is() { return "wm-navigation"; }
     static get encapsulation() { return "shadow"; }
@@ -126,7 +167,13 @@ export class Navigation {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Controls the open/closed state of the collapsible navigation. Has no effect\non viewports wider than 1024px where the navigation is always visible."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "open",
@@ -143,7 +190,10 @@ export class Navigation {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the collapsible navigation opens or closes. Consumed by\nwm-navigation-hamburger to keep its `aria-expanded` state in sync."
+                        }],
                     "text": ""
                 },
                 "complexType": {

package/dist/collection/components/wm-navigator/priv-navigator-button/priv-navigator-button.js

@@ -1,4 +1,8 @@
 import { h } from "@stencil/core";
+/**
+ * @internal
+ * @description Internal navigator button component for use with the Navigation component. Not to be used directly.
+ */
 export class PrivNavigatorButton {
     constructor() {
         this.expanded = false;
@@ -9,7 +13,7 @@ export class PrivNavigatorButton {
     }
     render() {
         const { handleClick, altText } = this;
-        return (h("button", { key: 'adfd184468176b7b9c025b5e4db3c86a1e857b4b', "aria-expanded": this.expanded.toString(), class: "navigator", onClick: handleClick.bind(this), "aria-label": altText }));
+        return (h("button", { key: '2f94dbb64a96096e852ec572f16264600c7fca8f', "aria-expanded": this.expanded.toString(), class: "navigator", onClick: handleClick.bind(this), "aria-label": altText }));
     }
     static get is() { return "priv-navigator-button"; }
     static get encapsulation() { return "shadow"; }