@watermarkinsights/ripple 5.31.0-alpha.6 → 5.31.0

package/dist/cjs/{app-globals-090d85be.js → app-globals-768940fa.js}

@@ -2,7 +2,7 @@
 
 require('./index-bb947bd5.js');
 
-const version = "5.31.0-alpha.6";
+const version = "5.31.0";
 
 // 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-090d85be.js');
+const appGlobals = require('./app-globals-768940fa.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-090d85be.js');
+const appGlobals = require('./app-globals-768940fa.js');
 
 /*
  Stencil Client Patch Browser v4.21.0 | MIT Licensed | https://stenciljs.com

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

@@ -177,8 +177,8 @@ const Toggletip = class {
     handleClick(ev) {
         if (this.isOpen) {
             const isElOrChild = ev.composedPath().includes(this.el);
-            const isButtonClick = ev.composedPath().includes(this.buttonEl);
-            if (isElOrChild && !isButtonClick) {
+            if (isElOrChild) {
+                // Re-announce if clicking any part of the component while open
                 this.announceToggletip();
             }
         }
@@ -238,11 +238,11 @@ const Toggletip = class {
         }
     }
     render() {
-        return (index.h(index.Host, { key: '321d03ab95c9e77b4e2b23fd833231e6fa03c64e', class: `size-${this.targetSize}` }, index.h("button", { key: '4d529ff8aa85c7802dbeca145ee0b82d6880d6db', ref: (el) => (this.buttonEl = el), class: "button", type: "button", "aria-label": this.label, popoverTarget: "toggletip", popoverTargetAction: "toggle", onClick: () => !this.isOpen && this.open(),
+        return (index.h(index.Host, { key: '4ec52955615c08a69684e5dc83eed0decc9fe73e', class: `size-${this.targetSize}` }, index.h("button", { key: '19e52e37cb2d712e47049f029d19ce7aaf03f111', ref: (el) => (this.buttonEl = el), class: "button", type: "button", "aria-label": this.label, popoverTarget: "toggletip", popoverTargetAction: "toggle", onClick: () => this.open(),
             // In order to position the tooltip identically to the toggletip, its presence is determined by these four events
-            onMouseEnter: () => !this.isOpen && functions.showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onMouseLeave: () => functions.hideTooltip(), onFocus: () => !this.isOpen && functions.showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onBlur: () => this.handleBlur() }, this.renderIcon()), index.h("div", { key: 'ccc4a3a9dfa81a1b0dd8fb4ecbca7976f2aff6dc', popover: "", ref: (el) => (this.toggletipEl = el), class: `toggletip ${this.targetSize} ${this.isHidden ? "hidden" : ""}`, id: "toggletip",
+            onMouseEnter: () => !this.isOpen && functions.showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onMouseLeave: () => functions.hideTooltip(), onFocus: () => !this.isOpen && functions.showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onBlur: () => this.handleBlur() }, this.renderIcon()), index.h("div", { key: '4cfdda63877a73b8f0ae74dc0f04f685f64a2c0a', popover: "", ref: (el) => (this.toggletipEl = el), class: `toggletip ${this.targetSize} ${this.isHidden ? "hidden" : ""}`, id: "toggletip",
             // @ts-ignore - despite what Typescript says, this is a valid event for popover elements
-            onToggle: (ev) => this.handlePopoverToggle(ev) }, this.tooltip), index.h("div", { key: '9dbfd9cf354be99641757f5a3495725b0e9c5485', ref: (el) => (this.liveRegionEl = el), class: "live-region sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" })));
+            onToggle: (ev) => this.handlePopoverToggle(ev) }, this.tooltip), index.h("div", { key: 'a563859bd11374774b51890693ff4da6a3b9f8e9', ref: (el) => (this.liveRegionEl = el), class: "live-region sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" })));
     }
     static get delegatesFocus() { return true; }
     get el() { return index.getElement(this); }

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

@@ -16,7 +16,8 @@ import { showTooltip, hideTooltip, shouldOpenUp, shouldOpenDown, shouldShiftLeft
  * @accessibility
  * - `label` sets the `aria-label` on the trigger button — required even though the button
  *   has a visual icon.
- * - The panel content is announced via `role="status"` / `aria-live="polite"` when opened.
+ * - The panel content is announced via `role="status"` / `aria-live="polite"` when opened,
+ *   and re-announced if the button is activated while the panel is already open.
  * - A hover/focus tooltip shows `"More information"` (info type) or `"Powered by AI"` (ai
  *   type) while the panel is closed.
  *
@@ -217,8 +218,8 @@ export class Toggletip {
     handleClick(ev) {
         if (this.isOpen) {
             const isElOrChild = ev.composedPath().includes(this.el);
-            const isButtonClick = ev.composedPath().includes(this.buttonEl);
-            if (isElOrChild && !isButtonClick) {
+            if (isElOrChild) {
+                // Re-announce if clicking any part of the component while open
                 this.announceToggletip();
             }
         }
@@ -278,11 +279,11 @@ export class Toggletip {
         }
     }
     render() {
-        return (h(Host, { key: '321d03ab95c9e77b4e2b23fd833231e6fa03c64e', class: `size-${this.targetSize}` }, h("button", { key: '4d529ff8aa85c7802dbeca145ee0b82d6880d6db', ref: (el) => (this.buttonEl = el), class: "button", type: "button", "aria-label": this.label, popoverTarget: "toggletip", popoverTargetAction: "toggle", onClick: () => !this.isOpen && this.open(),
+        return (h(Host, { key: '4ec52955615c08a69684e5dc83eed0decc9fe73e', class: `size-${this.targetSize}` }, h("button", { key: '19e52e37cb2d712e47049f029d19ce7aaf03f111', ref: (el) => (this.buttonEl = el), class: "button", type: "button", "aria-label": this.label, popoverTarget: "toggletip", popoverTargetAction: "toggle", onClick: () => this.open(),
             // In order to position the tooltip identically to the toggletip, its presence is determined by these four events
-            onMouseEnter: () => !this.isOpen && showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onMouseLeave: () => hideTooltip(), onFocus: () => !this.isOpen && showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onBlur: () => this.handleBlur() }, this.renderIcon()), h("div", { key: 'ccc4a3a9dfa81a1b0dd8fb4ecbca7976f2aff6dc', popover: "", ref: (el) => (this.toggletipEl = el), class: `toggletip ${this.targetSize} ${this.isHidden ? "hidden" : ""}`, id: "toggletip",
+            onMouseEnter: () => !this.isOpen && showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onMouseLeave: () => hideTooltip(), onFocus: () => !this.isOpen && showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onBlur: () => this.handleBlur() }, this.renderIcon()), h("div", { key: '4cfdda63877a73b8f0ae74dc0f04f685f64a2c0a', popover: "", ref: (el) => (this.toggletipEl = el), class: `toggletip ${this.targetSize} ${this.isHidden ? "hidden" : ""}`, id: "toggletip",
             // @ts-ignore - despite what Typescript says, this is a valid event for popover elements
-            onToggle: (ev) => this.handlePopoverToggle(ev) }, this.tooltip), h("div", { key: '9dbfd9cf354be99641757f5a3495725b0e9c5485', ref: (el) => (this.liveRegionEl = el), class: "live-region sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" })));
+            onToggle: (ev) => this.handlePopoverToggle(ev) }, this.tooltip), h("div", { key: 'a563859bd11374774b51890693ff4da6a3b9f8e9', ref: (el) => (this.liveRegionEl = el), class: "live-region sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" })));
     }
     static get is() { return "wm-toggletip"; }
     static get encapsulation() { return "shadow"; }

package/dist/docs/docs.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-01T20:56:49",
+  "timestamp": "2026-07-02T17:37:54",
   "compiler": {
     "name": "@stencil/core",
     "version": "4.21.0",
@@ -13187,7 +13187,7 @@
         },
         {
           "name": "accessibility",
-          "text": "- `label` sets the `aria-label` on the trigger button — required even though the button\n  has a visual icon.\n- The panel content is announced via `role=\"status\"` / `aria-live=\"polite\"` when opened.\n- A hover/focus tooltip shows `\"More information\"` (info type) or `\"Powered by AI\"` (ai\n  type) while the panel is closed."
+          "text": "- `label` sets the `aria-label` on the trigger button — required even though the button\n  has a visual icon.\n- The panel content is announced via `role=\"status\"` / `aria-live=\"polite\"` when opened,\n  and re-announced if the button is activated while the panel is already open.\n- A hover/focus tooltip shows `\"More information\"` (info type) or `\"Powered by AI\"` (ai\n  type) while the panel is closed."
         },
         {
           "name": "usageNotes",

package/dist/docs/skill/wm-action-menu.md

@@ -1,6 +1,5 @@
 ### Action Menu
 - **Element:** `<wm-action-menu>`
-- **Status:** stable
 
 **Purpose:** Dropdown interface that displays a list of action items. When closed it shows a text
 button, icon button, or selector box depending on action-menu-type. Selecting an item
@@ -46,8 +45,8 @@ one or more wm-menuitem children.
 - _(default)_ -- One or more wm-menuitem elements.
 
 **Events:**
-- `menuLoaded` _(deprecated: Use wmActionMenuLoaded instead.)_
-- `wmActionMenuLoaded`
+- `menuLoaded` -- Fires when the component finishes loading. _(deprecated: Use wmActionMenuLoaded instead.)_
+- `wmActionMenuLoaded` -- Fires when the component finishes loading and child wm-menuitem elements are ready.
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Button
 - **Element:** `<wm-button>`
-- **Status:** stable
 
 **Purpose:** Interactive button element that triggers actions and workflows. Has seven visual
 types plus AI variants.

package/dist/docs/skill/wm-chart-bar.md

@@ -1,6 +1,5 @@
 ### Chart Bar
 - **Element:** `<wm-chart-bar>`
-- **Status:** stable
 
 **Purpose:** Renders a horizontal bar chart for comparing values across nominal categories. Data and
 configuration are set via JavaScript properties (`chart.config` and `chart.data`) -- not

package/dist/docs/skill/wm-chart-column.md

@@ -1,6 +1,5 @@
 ### Chart Column
 - **Element:** `<wm-chart-column>`
-- **Status:** stable
 
 **Purpose:** Renders a vertical column chart for comparing values across nominal categories or showing
 distribution across interval/ratio ranges. Data and configuration are set via JavaScript

package/dist/docs/skill/wm-chart-legend.md

@@ -1,6 +1,5 @@
 ### Chart Legend
 - **Element:** `<wm-chart-legend>`
-- **Status:** stable
 
 **Purpose:** External legend component for wm-chart-bar and wm-chart-column. Retrieves color and label
 data from one or more charts via element IDs, allowing a single legend to serve multiple
@@ -27,9 +26,11 @@ charts automatically. _(default: `""`)_
 legend -- suitable for printed output. _(default: `false`)_
 
 **Events:**
-- `wmLegendItemClick` Detail: `{{ idx: number }} idx -- zero-based index of the clicked legend item, or
+- `wmLegendItemClick` -- Fires when the user clicks a legend item. The associated chart highlights
+the corresponding bar(s) and fades all others. Detail: `{{ idx: number }} idx -- zero-based index of the clicked legend item, or
 `-1` to clear all highlights.`
-- `wmLegendItemHover` Detail: `{{ idx: number }} idx -- zero-based index of the hovered legend item, or
+- `wmLegendItemHover` -- Fires when the user hovers over a legend item. The associated chart
+highlights the corresponding bar(s) and fades all others. Detail: `{{ idx: number }} idx -- zero-based index of the hovered legend item, or
 `-1` to clear all highlights.`
 
 **Code example:**

package/dist/docs/skill/wm-chart-slice.md

@@ -1,6 +1,5 @@
 ### Chart Slice
 - **Element:** `<wm-chart-slice>`
-- **Status:** stable
 
 **Purpose:** Data slice for a wm-chart composition chart. Each slice represents one segment of the whole.
 Always used as a direct child of wm-chart.

package/dist/docs/skill/wm-chart-stack.md

@@ -1,6 +1,5 @@
 ### Chart Stack
 - **Element:** `<wm-chart-stack>`
-- **Status:** stable
 
 **Purpose:** Renders a horizontal stacked bar chart: each stack's segments are sized as a percentage of
 that stack's total. Supports any number of stacks and segments, each occupying their own row.

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

@@ -1,6 +1,5 @@
 ### Chart
 - **Element:** `<wm-chart>`
-- **Status:** stable
 
 **Purpose:** Composition chart component rendering doughnut or stacked bar charts. Composed of a parent
 wm-chart element and wm-chart-slice children. Has 3 doughnut subtypes and 5 bar subtypes,

package/dist/docs/skill/wm-date-range.md

@@ -1,6 +1,5 @@
 ### Date Range
 - **Element:** `<wm-date-range>`
-- **Status:** stable
 
 **Purpose:** Two linked date inputs (start and end) with a shared calendar popup for selecting a date
 range. Users can type or click to set each date. Provides separate error states for start
@@ -53,16 +52,26 @@ Updated as the user types or picks from the calendar. _(default: `""`)_
 Updated as the user types or picks from the calendar. _(default: `""`)_
 
 **Events:**
-- `wmEndInputBlur`
-- `wmRangeSelection` Detail: `{{ startDate: { iso: string, us: string, int: string }, endDate: { iso: string, us: string, int: string } }}
+- `wmEndInputBlur` -- Fires when the end date input loses focus.
+- `wmRangeSelection` -- Fires when the user completes a range selection from the calendar popup. Detail: `{{ startDate: { iso: string, us: string, int: string }, endDate: { iso: string, us: string, int: string } }}
 startDate and endDate -- each formatted in ISO (YYYY-MM-DD), US (mm/dd/yyyy), and INT
 (dd/mm/yyyy). The dates are always returned in chronological order regardless of the order
 they were clicked.`
-- `wmStartInputBlur`
+- `wmStartInputBlur` -- Fires when the start date input loses focus.
 
 **Methods:**
-- `isValidISO(input?: string) => Promise<boolean>`
-- `reformatDate(inputFormat: string, outputFormat: string, date?: string) => Promise<string>`
+- `isValidISO(input?: string) => Promise<boolean>` -- Validates whether a string is a well-formed, calendar-correct ISO date
+(YYYY-MM-DD). Accounts for invalid day-of-month values and leap years.
+  - `input` -- - The string to validate.
+  - **Returns:** `true` if the string is a valid ISO date, `false` otherwise.
+- `reformatDate(inputFormat: string, outputFormat: string, date?: string) => Promise<string>` -- Converts a date string between `"US"` (mm/dd/yyyy), `"INT"` (dd/mm/yyyy),
+and `"ISO"` (YYYY-MM-DD). Direct US ↔ INT conversion is not supported -- route through
+ISO as an intermediate step.
+  - `inputFormat` -- - Format of the input date string (`"US"`, `"INT"`, or `"ISO"`).
+  - `outputFormat` -- - Desired output format (`"US"`, `"INT"`, or `"ISO"`).
+  - `date` -- - The date string to reformat.
+  - **Returns:** The reformatted date string, an empty string if `date` is omitted, or the original
+string unchanged if it cannot be parsed.
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Datepicker
 - **Element:** `<wm-datepicker>`
-- **Status:** stable
 
 **Purpose:** Date input that lets users type a date or pick one from a calendar popup. Supports
 configurable date formats, pre-selection, validation, and full keyboard navigation of the calendar.
@@ -37,12 +36,27 @@ _None documented_
 - `value` -- The date displayed in the input field, in the format specified by `date-format`. Updated as the user types. Can also be set programmatically by the application. _(default: `""`)_
 
 **Events:**
-- `wmDatepickerDateSelected` Detail: `{{ date: string }} date -- the selected date in ISO format (YYYY-MM-DD).`
-- `wmDatepickerInputBlurred`
+- `wmDatepickerDateSelected` -- Fires when the user selects a date from the calendar popup. Detail: `{{ date: string }} date -- the selected date in ISO format (YYYY-MM-DD).`
+- `wmDatepickerInputBlurred` -- Fires when the text input loses focus.
 
 **Methods:**
-- `isValidIso(input?: string) => Promise<boolean>`
-- `reformatDate(inputFormat: "US" | "INT" | "ISO", outputFormat: "US" | "INT" | "ISO", date?: string) => Promise<string>`
+- `isValidIso(input?: string) => Promise<boolean>` -- Validates whether a string is a well-formed, calendar-correct ISO date
+(YYYY-MM-DD). Accounts for invalid day-of-month values and leap years.
+  - `input` -- - The string to validate.
+  - **Returns:** `true` if the string is a valid ISO date, `false` otherwise.
+  - **Example:** `isValidIso("1969-06-20") // -> true`
+  - **Example:** `isValidIso("1969-06-33") // -> false (day 33 does not exist)`
+  - **Example:** `isValidIso("2023-02-29") // -> false (2023 is not a leap year)`
+- `reformatDate(inputFormat: "US" | "INT" | "ISO", outputFormat: "US" | "INT" | "ISO", date?: string) => Promise<string>` -- Converts a date string between the supported format tokens: `"US"` (mm/dd/yyyy),
+`"INT"` (dd/mm/yyyy), and `"ISO"` (YYYY-MM-DD). Direct US ↔ INT conversion is not supported --
+route through ISO as an intermediate step.
+  - `inputFormat` -- - Format of the input date string.
+  - `outputFormat` -- - Desired output format.
+  - `date` -- - The date string to reformat.
+  - **Returns:** The reformatted date string, an empty string if `date` is omitted or falsy, or the
+original string unchanged if it cannot be parsed.
+  - **Example:** `reformatDate("US", "ISO", "06/20/1969") // -> "1969-06-20"`
+  - **Example:** `reformatDate("ISO", "US", "1969-06-20") // -> "06/20/1969"`
 
 **Accessibility:**
 

package/dist/docs/skill/wm-file-list.md

@@ -1,6 +1,5 @@
 ### File List
 - **Element:** `<wm-file-list>`
-- **Status:** stable
 
 **Purpose:** Read-only list of files with optional preview and download actions. Visually similar to the
 Uploader but with no upload capability. Use when displaying existing files users can view or

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

@@ -1,6 +1,5 @@
 ### File
 - **Element:** `<wm-file>`
-- **Status:** stable
 
 **Purpose:** Displays a single file row with its name, optional metadata, and configurable action buttons
 (preview, download, delete). Adapts responsively -- at narrow widths action buttons collapse
@@ -31,10 +30,10 @@ from the parent wm-file-list or wm-uploader when set there. _(type: `"all" | "la
 (e.g. `"Uploaded by Smith, John"`).
 
 **Events:**
-- `wmFileDelete`
-- `wmFileDownload`
-- `wmFileErrorCleared`
-- `wmFilePreview`
+- `wmFileDelete` -- Fires when the delete button is clicked.
+- `wmFileDownload` -- Fires when the download button is clicked.
+- `wmFileErrorCleared` -- Fires when the user clears a file error by clicking the Clear button.
+- `wmFilePreview` -- Fires when the preview button is clicked.
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Flyout
 - **Element:** `<wm-flyout>`
-- **Status:** stable
 
 **Purpose:** Slide-in panel that renders over the main content as a modal dialog. Used for detail views,
 multi-step workflows, and forms that require focus without navigating away from the page.
@@ -65,13 +64,16 @@ in the footer. Fires `wmFlyoutSecondaryTriggered` when clicked.
 - _(default)_ -- Main content of the flyout body.
 
 **Events:**
-- `wmFlyoutBreadcrumbClicked` Detail: `{{ breadcrumb: string, index: number }} breadcrumb -- the label of the clicked breadcrumb; index -- its zero-based position in the original CSV list.`
-- `wmFlyoutCloseTriggered`
-- `wmFlyoutPrimaryTriggered`
-- `wmFlyoutSecondaryTriggered`
+- `wmFlyoutBreadcrumbClicked` -- Fires when a breadcrumb button (any non-last breadcrumb) is clicked. Detail: `{{ breadcrumb: string, index: number }} breadcrumb -- the label of the clicked breadcrumb; index -- its zero-based position in the original CSV list.`
+- `wmFlyoutCloseTriggered` -- Fires when the close button is clicked, Escape is pressed, or the native
+dialog close event fires. The host application must set `open` to false in response.
+- `wmFlyoutPrimaryTriggered` -- Fires when the primary footer button is clicked.
+- `wmFlyoutSecondaryTriggered` -- Fires when the secondary footer button is clicked.
 
 **Methods:**
-- `focusHeading() => Promise<void>`
+- `focusHeading() => Promise<void>` -- Moves focus to the flyout's heading element. Call this after updating flyout
+content in a multi-step workflow so screen readers announce the new heading to the user.
+  - **Returns:** A promise that resolves once focus has been applied.
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Input
 - **Element:** `<wm-input>`
-- **Status:** stable
 
 **Purpose:** Accessible single-line text input. Supports text and number types, character limits,
 symbol prefixes/suffixes, and inline info/error messaging. Use instead of a native
@@ -52,7 +51,8 @@ symbol prefixes/suffixes, and inline info/error messaging. Use instead of a nati
 - `value` -- The initial value of the input field, or its current value when reading from the component. _(default: `""`)_
 
 **Events:**
-- `wmInputValueChanged` Detail: `{{ value: string }} value -- the current value of the input at the time of blur.`
+- `wmInputValueChanged` -- Fires on blur when the input value has changed since the last blur. Use the
+native `input` event if you need to react to every keystroke. Detail: `{{ value: string }} value -- the current value of the input at the time of blur.`
 
 **Accessibility:**
 

package/dist/docs/skill/wm-line-chart.md

@@ -1,6 +1,5 @@
 ### Line Chart
 - **Element:** `<wm-line-chart>`
-- **Status:** stable
 
 **Purpose:** Visualizes how data changes over time. Ideal for trend analysis -- tracking one or more
 metrics across chronological intervals such as semesters, academic years, or months.

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

@@ -1,6 +1,5 @@
 ### Menuitem
 - **Element:** `<wm-menuitem>`
-- **Status:** stable
 
 **Purpose:** A single item within a wm-action-menu dropdown. Always used as a direct child of
 wm-action-menu -- never rendered in isolation.
@@ -23,7 +22,8 @@ or an MDI character code (deprecated). Incompatible with `description`.
 - _(default)_ -- The visible label text for the menu item.
 
 **Events:**
-- `wmMenuitemClicked`
+- `wmMenuitemClicked` -- Fires when the menu item is clicked or Enter is pressed while focused.
+Consumed by the parent wm-action-menu to close the dropdown.
 
 **Accessibility:**
 

package/dist/docs/skill/wm-modal-footer.md

@@ -1,6 +1,5 @@
 ### Modal Footer
 - **Element:** `<wm-modal-footer>`
-- **Status:** stable
 
 **Purpose:** Footer section for a wm-modal. Renders a primary action button, an optional secondary
 button, and optional informational text. Button clicks delegate to the parent modal's

package/dist/docs/skill/wm-modal-header.md

@@ -1,6 +1,5 @@
 ### Modal Header
 - **Element:** `<wm-modal-header>`
-- **Status:** stable
 
 **Purpose:** Header section for a wm-modal. Renders the modal title, an optional subheading, and the
 close button. Always used as a direct child of wm-modal -- never rendered in isolation.

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

@@ -1,6 +1,5 @@
 ### Modal
 - **Element:** `<wm-modal>`
-- **Status:** stable
 
 **Purpose:** 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,
@@ -54,14 +53,22 @@ generated if absent -- do not set this prop manually. _(required)_
 - _(default)_ -- Modal content: wm-modal-header, body content, and wm-modal-footer.
 
 **Events:**
-- `wmModalCloseTriggered`
-- `wmModalPrimaryTriggered`
-- `wmModalSecondaryTriggered`
+- `wmModalCloseTriggered` -- Fires when the close button is clicked or Escape is pressed. Does not bubble,
+preventing nested modals from closing simultaneously. The host application must set `open`
+to false in response.
+- `wmModalPrimaryTriggered` -- Fires when the wm-modal-footer primary button is clicked.
+- `wmModalSecondaryTriggered` -- Fires when the wm-modal-footer secondary button is clicked.
 
 **Methods:**
-- `emitCloseEvent() => Promise<void>`
-- `emitPrimaryEvent() => Promise<void>`
-- `emitSecondaryEvent() => Promise<void>`
+- `emitCloseEvent() => Promise<void>` -- 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.
+- `emitPrimaryEvent() => Promise<void>` -- 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.
+- `emitSecondaryEvent() => Promise<void>` -- 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.
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Navigation Hamburger
 - **Element:** `<wm-navigation-hamburger>`
-- **Status:** stable
 
 **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
@@ -29,7 +28,8 @@ _None documented_
 linking and for keeping `aria-expanded` in sync with the navigation's open state.
 
 **Events:**
-- `wmNavigationHamburgerClicked`
+- `wmNavigationHamburgerClicked` -- Fires when the button is clicked. Consumed by the associated wm-navigation
+to toggle its `open` state -- not intended for direct application use.
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Navigation Item
 - **Element:** `<wm-navigation-item>`
-- **Status:** stable
 
 **Purpose:** 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.
@@ -33,7 +32,8 @@ _None documented_
 - _(default)_ -- Optional icon element displayed before the link text.
 
 **Events:**
-- `wmNavigationItemClicked`
+- `wmNavigationItemClicked` -- Fires when the link is clicked. Consumed by the parent wm-navigation to
+close the collapsible menu on narrow viewports.
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Navigation
 - **Element:** `<wm-navigation>`
-- **Status:** stable
 
 **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
@@ -34,7 +33,8 @@ on viewports wider than 1024px where the navigation is always visible. _(default
 - _(default)_ -- One or more wm-navigation-item elements.
 
 **Events:**
-- `wmNavigationStateChanged`
+- `wmNavigationStateChanged` -- Fires when the collapsible navigation opens or closes. Consumed by
+wm-navigation-hamburger to keep its `aria-expanded` state in sync.
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Navigator
 - **Element:** `<wm-navigator>`
-- **Status:** stable
 
 **Purpose:** User account menu that displays the logged-in user's name, email, and a product switcher
 for navigating between Watermark applications. Renders as a button that opens a dropdown
@@ -48,7 +47,9 @@ Each object must include `id`, `name`, `icon_url`, and either `link_url` (auth-t
 - `user-name` -- The display name of the logged-in user, shown in the menu header.
 
 **Events:**
-- `wmNavigatorLogout`
+- `wmNavigatorLogout` -- Fires when the user clicks the logout option. Always handle this event to
+run app-specific cleanup (e.g. clearing local storage or session state) before any logout
+redirect. If `logout-url` is set, the component will navigate there after this event fires.
 
 **Accessibility:**
 

package/dist/docs/skill/wm-nested-select.md

@@ -1,6 +1,5 @@
 ### Nested Select
 - **Element:** `<wm-nested-select>`
-- **Status:** stable
 
 **Purpose:** Dropdown list of grouped options that allows single or multi-select. Like wm-select but
 options are organized into labeled categories via a two-level hierarchy. Composed of a
@@ -57,7 +56,8 @@ group. _(default: `false`)_
 `multiple` to be set. _(default: `false`)_
 
 **Events:**
-- `wmNestedSelectBlurred`
+- `wmNestedSelectBlurred` -- Fires when focus leaves the component entirely (not when moving between
+internal elements such as options or group buttons).
 
 **Accessibility:**
 

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

@@ -1,6 +1,5 @@
 ### Optgroup
 - **Element:** `<wm-optgroup>`
-- **Status:** stable
 
 **Purpose:** Named group of wm-option elements used inside wm-nested-select. Renders as a slide-in
 panel that appears when the user selects the group from the top-level menu.
@@ -20,11 +19,13 @@ of its options. _(default: `false`)_
 dropdown menu. _(required)_
 
 **Events:**
-- `wmOptgroupAllDeselected`
-- `wmOptgroupAllSelected`
+- `wmOptgroupAllDeselected` -- Fires when the "Deselect All" button inside this group is activated.
+- `wmOptgroupAllSelected` -- Fires when the "Select All" button inside this group is activated.
 
 **Methods:**
-- `emitDeselection() => Promise<void>`
+- `emitDeselection() => Promise<void>` -- Programmatically deselects all options in this group by emitting
+`wmOptgroupAllDeselected`.
+  - **Returns:** `Promise<void>`
 
 **Code example:**
 

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

@@ -1,6 +1,5 @@
 ### Option
 - **Element:** `<wm-option>`
-- **Status:** stable
 
 **Purpose:** Individual selectable item used inside wm-select, wm-nested-select (via wm-optgroup), and
 wm-optgroup. Renders as a listbox option with optional secondary text.
@@ -24,8 +23,8 @@ or modifies this value -- it is purely a pass-through for application code to at
 or key. _(type: `null | string`)_
 
 **Events:**
-- `wmOptionDeselected` Detail: ``HTMLWmOptionElement` -- the option element that was deselected.`
-- `wmOptionSelected` Detail: ``HTMLWmOptionElement` -- the option element that was selected.`
+- `wmOptionDeselected` -- Fires when this option is deselected by the user (multiselect mode only). Detail: ``HTMLWmOptionElement` -- the option element that was deselected.`
+- `wmOptionSelected` -- Fires when this option is selected by the user. Detail: ``HTMLWmOptionElement` -- the option element that was selected.`
 
 **Code example:**
 

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

@@ -1,6 +1,5 @@
 ### Pagination
 - **Element:** `<wm-pagination>`
-- **Status:** stable
 
 **Purpose:** Pagination controls for navigating large data sets. Renders a full page-number strip on
 wider viewports and a minimal prev/next/first/last layout on narrow viewports. Does not
@@ -45,7 +44,9 @@ calculate the total page count.
 `event.target.value` in the `wmPaginationPageClicked` handler to get the selected page. _(default: `1`)_
 
 **Events:**
-- `wmPaginationPageClicked`
+- `wmPaginationPageClicked` -- Fires when the user clicks a page number, previous, or next button.
+Read `event.target.value` to get the selected page number, then update `current-page`
+and re-render your data.
 
 **Accessibility:**
 

package/dist/docs/skill/wm-progress-indicator.md

@@ -1,6 +1,5 @@
 ### Progress Indicator
 - **Element:** `<wm-progress-indicator>`
-- **Status:** stable
 
 **Purpose:** Single progress indicator used inside a wm-progress-monitor. Renders the binary completion
 data for one category as either a doughnut chart (wide layout) or a horizontal bar (narrow

package/dist/docs/skill/wm-progress-monitor.md

@@ -1,6 +1,5 @@
 ### Progress Monitor
 - **Element:** `<wm-progress-monitor>`
-- **Status:** stable
 
 **Purpose:** Container for one or more wm-progress-indicator elements, each showing binary completion
 progress (e.g. "Completed" vs "Not Completed"). Above the layout breakpoint, indicators
@@ -33,7 +32,8 @@ and collapses to bars when it cannot. _(type: `number | string`)_
 in bar layout mode (e.g. `"Completed,Not Completed"`). Keys cannot contain commas.
 
 **Events:**
-- `wmProgressMonitorModeChange` Detail: ``"doughnut" | "bar"` -- the new layout mode.`
+- `wmProgressMonitorModeChange` -- Fires once on load and again whenever the layout switches between `"doughnut"`
+and `"bar"` modes. Use this to synchronize external UI that depends on the current layout. Detail: ``"doughnut" | "bar"` -- the new layout mode.`
 
 **Code example:**
 

package/dist/docs/skill/wm-progress-slice.md

@@ -1,6 +1,5 @@
 ### Progress Slice
 - **Element:** `<wm-progress-slice>`
-- **Status:** stable
 
 **Purpose:** Data slice for a wm-progress-indicator. Represents one state (complete or incomplete) in
 a binary progress chart. Always used as a direct child of wm-progress-indicator.