@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/collection/components/selects/wm-nested-select/wm-nested-select.js

@@ -1,6 +1,104 @@
 import { h, Host, forceUpdate } from "@stencil/core";
 import { getContextMeasurements, getTextDir, isElOrChild, shouldOpenUp, toBool, showTooltip, hideTooltip, } from "../../../global/functions";
 import { globalMessages, selectMessages } from "../../../global/intl";
+/**
+ * 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
+ * parent wm-nested-select, one or more wm-optgroup children, and wm-option elements inside
+ * each group.
+ *
+ * @keyboardInteraction
+ * - **Closed button**: Space / Enter / Arrow Down opens the dropdown and focuses the first
+ *   group; Arrow Up opens and focuses the last group.
+ * - **Group level**: Arrow Up / Down navigate group buttons; Arrow Right / Enter enters the
+ *   group; Escape closes the dropdown.
+ * - **Option level (inside a group)**: Arrow Up / Down navigate options; Arrow Left returns
+ *   to the group list; Home / End jump to first / last option; typing a letter jumps to the
+ *   first matching option.
+ * - **Tab** (anywhere in dropdown): Closes the dropdown.
+ *
+ * @accessibility
+ * - `label` is required even when `label-position` is `"none"` — it is used as the dropdown's
+ *   ARIA accessible name.
+ * - Group buttons render with `role="menuitem"` inside a `role="menu"`. The option level
+ *   renders as a `role="listbox"` with `role="option"` items.
+ * - Validation errors are announced via an `aria-live` region when `error-message` changes.
+ *
+ * @usageNotes
+ * - Selection state is maintained via the `selected` prop on each wm-option child.
+ * - To respond to selection changes, listen for `wmOptionSelected` (declared on wm-option but
+ *   bubbles to wm-nested-select). `event.detail` is the `HTMLWmOptionElement`; read `.value`
+ *   or `.textContent` to get the selected value.
+ * - `select-all` adds a "Select All / Deselect All" toggle at the top of each group; it
+ *   requires `multiple` to be set.
+ * - `search` filters options within the currently open group only.
+ *
+ * @example {html} Single-select nested select
+ * <wm-nested-select label="Department">
+ *   <wm-optgroup label="Sciences">
+ *     <wm-option selected>Select a department</wm-option>
+ *     <wm-option>Biology</wm-option>
+ *   </wm-optgroup>
+ *   <wm-optgroup label="Humanities">
+ *     <wm-option>English</wm-option>
+ *   </wm-optgroup>
+ * </wm-nested-select>
+ *
+ * @example {react} Single-select nested select
+ * const [department, setDepartment] = useState('');
+ *
+ * // event.detail is the selected HTMLWmOptionElement
+ * const handleSelect = (event) => {
+ *   setDepartment(event.detail.value ?? event.detail.textContent);
+ * };
+ *
+ * <WmNestedSelect label="Department" onWmOptionSelected={handleSelect}>
+ *   <WmOptgroup label="Sciences">
+ *     <WmOption selected>Select a department</WmOption>
+ *     <WmOption value="bio">Biology</WmOption>
+ *   </WmOptgroup>
+ *   <WmOptgroup label="Humanities">
+ *     <WmOption value="eng">English</WmOption>
+ *   </WmOptgroup>
+ * </WmNestedSelect>
+ *
+ * @example {html} Multi-select with Select All
+ * <wm-nested-select label="Programs" multiple select-all>
+ *   <wm-optgroup label="Sciences">
+ *     <wm-option value="bio">Biology</wm-option>
+ *     <wm-option value="chem">Chemistry</wm-option>
+ *   </wm-optgroup>
+ * </wm-nested-select>
+ *
+ * @example {react} Multi-select with Select All
+ * const [selected, setSelected] = useState([]);
+ *
+ * // event.detail is the HTMLWmOptionElement that was selected or deselected
+ * const handleSelect = (event) => {
+ *   const value = event.detail.value ?? event.detail.textContent;
+ *   setSelected((prev) => [...prev, value]);
+ * };
+ *
+ * const handleDeselect = (event) => {
+ *   const value = event.detail.value ?? event.detail.textContent;
+ *   setSelected((prev) => prev.filter((v) => v !== value));
+ * };
+ *
+ * <WmNestedSelect
+ *   label="Programs"
+ *   multiple={true}
+ *   selectAll={true}
+ *   onWmOptionSelected={handleSelect}
+ *   onWmOptionDeselected={handleDeselect}
+ * >
+ *   <WmOptgroup label="Sciences">
+ *     <WmOption value="bio">Biology</WmOption>
+ *     <WmOption value="chem">Chemistry</WmOption>
+ *   </WmOptgroup>
+ * </WmNestedSelect>
+ *
+ * @category Basic Controls
+ */
 export class NestedSelect {
     constructor() {
         this.openUp = false;
@@ -291,16 +389,16 @@ export class NestedSelect {
                 this.isExpanded ? this.close() : this.open();
             },
         };
-        return (h(Host, { key: '7e8ed5b276c45f62f8d92521e65b6b6dded568db', onBlur: (ev) => this.handleComponentBlur(ev) }, h("div", { key: '8712a1df1e10912a4e69b6584b1f47670f9fe0ef', class: `wrapper ${getTextDir()} label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: '6a4e9d87422861362ac87b92703dd094748da7e9', class: "label-wrapper" }, h("label", { key: 'e27736516799cf708681ee19eafd179094dd5096', class: "label", id: "label", htmlFor: "selectbtn", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label), 
+        return (h(Host, { key: '2b2047fde46afe93d6364c697aa186544f5663f9', onBlur: (ev) => this.handleComponentBlur(ev) }, h("div", { key: '37032e6c0098cb6339f32e82523a7207950579d6', class: `wrapper ${getTextDir()} label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: 'd92559365f28d589bb1c47da2fb489ccf20a1f8c', class: "label-wrapper" }, h("label", { key: '1f19bf5a5d5943acdc8a55e01c04f0bc9875d66c', class: "label", id: "label", htmlFor: "selectbtn", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label), 
         // we can't use aria-required because the listbox is in a sub-component and it is not announced
-        this.labelPosition !== "none" && this.requiredField && (h("span", { key: '0d6e9bc7134d9ce46d53813067eeef7f2af50e81', class: "required" }, h("span", { key: 'a4dd0ef025cf32566f863ce0119e72259d9ca50e', class: "sr-only" }, globalMessages.requiredField), h("span", { key: '8169eaa0d995f90e49e5beb9c66dbac4cf93cc6d', "aria-hidden": "true" }, "*")))), h("div", { key: 'a84486ea919cc9cf713c3f98322b6f8f10e91e84', class: "button-wrapper" }, h("button", Object.assign({ key: 'd8605fbcab85f7c15cb030214e599654a3bbeb5e' }, buttonProps, { class: "displayedoption", ref: (el) => (this.buttonEl = el), onBlur: (ev) => this.handleButtonBlur(ev) }), h("span", { key: 'ce7182acce7ac9f9bf4259fc73155ec1b8b765a2', class: "overflowcontrol" }, h("span", { key: 'dcda39e2afe152b5c3a75d92e9795f4a4fe93858', class: "button-text" }, this.renderButtonText())), h("div", { key: '8061497676ac1e2c4075f93416663f09b8687ff4', class: `expand-icon svg-icon ${this.isExpanded ? "svg-expand-less" : "svg-expand-more"}` }), this.renderOverflowCount(), h("div", { key: '4a234681f6ccaf3860e46f193855b56e46e2b221', ref: (el) => (this.measurementAreaEl = el), class: "measurement-area", "aria-hidden": "true" })), h("div", { key: '4a73cad886a38ba1674241b0a5147d3941c4f97e', class: `dropdown  ${this.openUp ? "upwards" : ""}`, ref: (el) => (this.dropdownEl = el) }, this.renderClearSelectionButton(), h("div", { key: '4660e100c2e0c5291cced7a26a58143a25852f0a', ref: (el) => (this.menuEl = el), id: "menu", role: "menu", class: this.isGroupExpanded ? "hidden" : "", style: { "--max-height": this.constrainedMaxHeight }, tabIndex: -1 }, this.optgroupEls.map((optgroupEl) => {
+        this.labelPosition !== "none" && this.requiredField && (h("span", { key: '21d397924616a6b3ec214ad438e1fd6a3630a83f', class: "required" }, h("span", { key: '47f761e0718b4feefffa83c58b801310668c7c80', class: "sr-only" }, globalMessages.requiredField), h("span", { key: '765a9ec20cc464e15efd65ab28700953dbdd5299', "aria-hidden": "true" }, "*")))), h("div", { key: '9ed5ab01e3cfc907e3cf65840539fa6c23c949fd', class: "button-wrapper" }, h("button", Object.assign({ key: 'd0407a5647471c985a504d4023af1223b3439c7e' }, buttonProps, { class: "displayedoption", ref: (el) => (this.buttonEl = el), onBlur: (ev) => this.handleButtonBlur(ev) }), h("span", { key: '1f050a070e82db4ebf55dab04102f4297a8cc431', class: "overflowcontrol" }, h("span", { key: '9fa87143404b5e0c15051c7c2e31cb0d566c7709', class: "button-text" }, this.renderButtonText())), h("div", { key: '97070ef2749ba4b4122008ed6f37b9b5ac10074f', class: `expand-icon svg-icon ${this.isExpanded ? "svg-expand-less" : "svg-expand-more"}` }), this.renderOverflowCount(), h("div", { key: 'b3d36bb8bfe445bef0a2f131f93f683a12aa5b53', ref: (el) => (this.measurementAreaEl = el), class: "measurement-area", "aria-hidden": "true" })), h("div", { key: 'e18f43067a2aad2012f706e0d17fd9aba64844c3', class: `dropdown  ${this.openUp ? "upwards" : ""}`, ref: (el) => (this.dropdownEl = el) }, this.renderClearSelectionButton(), h("div", { key: 'c7ddaa0e27eb0fb722467acce7cd9cb57fb2055f', ref: (el) => (this.menuEl = el), id: "menu", role: "menu", class: this.isGroupExpanded ? "hidden" : "", style: { "--max-height": this.constrainedMaxHeight }, tabIndex: -1 }, this.optgroupEls.map((optgroupEl) => {
             return (h("button", { class: `menuitem group-btn ${optgroupEl.disabled ? "disabled" : ""}`, role: "menuitem", "data-label": optgroupEl.label, tabindex: -1, "aria-disabled": optgroupEl.disabled, onClick: () => {
                     if (!optgroupEl.disabled) {
                         optgroupEl.isExpanded = !optgroupEl.isExpanded;
                         forceUpdate(this.el);
                     }
                 }, onKeyDown: (ev) => this.handleMenuitemKeydown(ev) }, h("div", { class: "option-text" }, h("span", null, optgroupEl.label), this.renderSelectionCount(optgroupEl), optgroupEl.disabled && h("div", { class: "disabled-indication" }, "Disabled")), h("div", { class: "svg-icon svg-next" })));
-        })), h("div", { key: 'cd880112ee35cdc1a2a3dafa210db9837426fc47', class: `option-list-wrapper ${this.isGroupExpanded ? "" : "hidden"}` }, h("slot", { key: 'f617faa2bbb0f34e500ec103704d3d1298d3f08d' }))), h("div", { key: '0020de125ad2ada89d5f0b38e3af6396879b4de6', id: "error", class: this.errorMessage ? "error-message" : "" }, this.errorMessage))), h("div", { key: 'ecc4b501c84e72461319863f4e6b5c6afc3aa944', id: "nestedselect-announcement", "aria-live": "assertive", "aria-atomic": "true", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement)));
+        })), h("div", { key: '09aa4f1e8277d540b20a8c7bdbafb0f81e8b6e96', class: `option-list-wrapper ${this.isGroupExpanded ? "" : "hidden"}` }, h("slot", { key: 'a33786c858d61d450926d17f514727aa87a4f5e0' }))), h("div", { key: '2022accefbc295da08a807d2a3d600dd38f86a2c', id: "error", class: this.errorMessage ? "error-message" : "" }, this.errorMessage))), h("div", { key: '3ac96561df791f14d4163d1f6ef19e8e25fe4040', id: "nestedselect-announcement", "aria-live": "assertive", "aria-atomic": "true", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement)));
     }
     static get is() { return "wm-nested-select"; }
     static get encapsulation() { return "shadow"; }
@@ -328,7 +426,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the entire nested select component, preventing any interaction."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -346,7 +450,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Overrides the maximum height of the options dropdown. Accepts any valid CSS\nlength value (e.g. `\"300px\"`)."
+                        }, {
+                            "name": "default",
+                            "text": "\"200px\""
+                        }],
                     "text": ""
                 },
                 "attribute": "max-height",
@@ -364,7 +474,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible label describing the dropdown's purpose. Required even when\n`label-position` is `\"none\"` \u2014 it is used as the ARIA accessible name for the button."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "label",
@@ -381,7 +497,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Controls where the label is rendered relative to the dropdown button.\n`\"none\"` hides the label visually but keeps it accessible."
+                        }, {
+                            "name": "default",
+                            "text": "\"top\""
+                        }],
                     "text": ""
                 },
                 "attribute": "label-position",
@@ -399,7 +521,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Renders a required-field asterisk (*) next to the label."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "required-field",
@@ -417,7 +545,10 @@ export class NestedSelect {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Displays the component in an error state with the provided message shown\nbeneath the button."
+                        }],
                     "text": ""
                 },
                 "attribute": "error-message",
@@ -434,7 +565,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Enables multiselect mode, allowing more than one option to be selected at\na time."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "multiple",
@@ -452,7 +589,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Adds a search input that filters visible options within the currently open\ngroup."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "search",
@@ -470,7 +613,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Adds a \"Select All / Deselect All\" toggle at the top of each group. Requires\n`multiple` to be set."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "select-all",
@@ -488,7 +637,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Text displayed in the trigger button when no options are selected."
+                        }, {
+                            "name": "default",
+                            "text": "Locale-specific placeholder string"
+                        }],
                     "text": ""
                 },
                 "attribute": "placeholder",
@@ -506,7 +661,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Placeholder text displayed inside the search input when `search` is enabled."
+                        }, {
+                            "name": "default",
+                            "text": "Locale-specific search placeholder string"
+                        }],
                     "text": ""
                 },
                 "attribute": "search-placeholder",
@@ -524,7 +685,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Text displayed in the trigger button when all options across all groups are\nselected (multiselect mode)."
+                        }, {
+                            "name": "default",
+                            "text": "Locale-specific \"all selected\" string"
+                        }],
                     "text": ""
                 },
                 "attribute": "all-selected-message",
@@ -542,7 +709,13 @@ export class NestedSelect {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Constrains the dropdown height when it opens upward and available space above\nis less than maxHeight. Set programmatically \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "attribute": "constrained-max-height",
@@ -567,7 +740,10 @@ export class NestedSelect {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when focus leaves the component entirely (not when moving between\ninternal elements such as options or group buttons)."
+                        }],
                     "text": ""
                 },
                 "complexType": {

package/dist/collection/components/selects/wm-optgroup/wm-optgroup.js

@@ -1,5 +1,46 @@
 import { h, Host } from "@stencil/core";
 import { handleDisabledAttribute, toBool } from "../../../global/functions";
+/**
+ * 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.
+ *
+ * @usageNotes
+ * - Always used as a direct child of wm-nested-select.
+ * - `label` is required — it is shown as the group heading in the dropdown menu.
+ * - The `disabled` prop prevents the group button from being clicked, hiding all its options.
+ * - `wmOptgroupAllSelected` and `wmOptgroupAllDeselected` are fired when the "Select All /
+ *   Deselect All" button inside the group is activated; they bubble to wm-nested-select.
+ *
+ * @example {html} Optgroup inside nested select
+ * <wm-nested-select label="Department">
+ *   <wm-optgroup label="Sciences">
+ *     <wm-option selected>Select a department</wm-option>
+ *     <wm-option>Biology</wm-option>
+ *   </wm-optgroup>
+ * </wm-nested-select>
+ *
+ * @example {react} Optgroup inside nested select
+ * <WmNestedSelect label="Department">
+ *   <WmOptgroup label="Sciences">
+ *     <WmOption selected={true}>Select a department</WmOption>
+ *     <WmOption>Biology</WmOption>
+ *   </WmOptgroup>
+ * </WmNestedSelect>
+ *
+ * @example {html} Disabled optgroup
+ * <wm-nested-select label="Program">
+ *   <wm-optgroup label="Sciences" disabled>
+ *     <wm-option>Biology</wm-option>
+ *   </wm-optgroup>
+ * </wm-nested-select>
+ *
+ * @example {react} Disabled optgroup
+ * <WmNestedSelect label="Program">
+ *   <WmOptgroup label="Sciences" disabled={true}>
+ *     <WmOption>Biology</WmOption>
+ *   </WmOptgroup>
+ * </WmNestedSelect>
+ */
 export class Optgroup {
     constructor() {
         this.label = undefined;
@@ -35,9 +76,19 @@ export class Optgroup {
             this.optionListEl.updateOptionVisibility();
         }
     }
+    /**
+     * @description Programmatically deselects all options in this group by emitting
+     * `wmOptgroupAllDeselected`.
+     * @returns `Promise<void>`
+     */
     async emitDeselection() {
         this.wmOptgroupAllDeselected.emit();
     }
+    /**
+     * @internal
+     * @description Notifies the internal option list that child options have changed so it can
+     * refresh clone state — not for application use.
+     */
     async handleChildChange() {
         this.optionListEl.handleChildChange();
     }
@@ -48,7 +99,7 @@ export class Optgroup {
         handleDisabledAttribute(this.el, this.isDisabled);
     }
     render() {
-        return (h(Host, { key: 'f0aab9a65cc5d21105c75bdc3768e0076123c0c8' }, h("div", { key: '23429cfad03b7026205ed0aef92973353d3ccff0', class: `list-wrapper` }, h("priv-option-list", { key: '6d8d1ea6e0ab9394bec5f4cf5423941fd9979332', ref: (el) => (this.optionListEl = el), multiple: this.parentNestedSelect.multiple, search: this.parentNestedSelect.search, maxHeight: this.parentNestedSelect.constrainedMaxHeight, searchPlaceholder: this.parentNestedSelect.searchPlaceholder, optgroupLabel: this.label, selectAll: this.parentNestedSelect.selectAll, onOptionListAllSelected: () => this.wmOptgroupAllSelected.emit(), onOptionListAllDeselected: () => this.wmOptgroupAllDeselected.emit() }, h("slot", { key: 'e01aeec2a2c3cd346f821c1fe46d7e77944e4f98' })))));
+        return (h(Host, { key: '765770ff80d0c9cca3f06a23850306405cf8e5df' }, h("div", { key: 'b503e82de1025ec673496f4f81aae0dad8d0cb8b', class: `list-wrapper` }, h("priv-option-list", { key: 'dc84a7558f8821ff8249cd4ba5702f8d58f13523', ref: (el) => (this.optionListEl = el), multiple: this.parentNestedSelect.multiple, search: this.parentNestedSelect.search, maxHeight: this.parentNestedSelect.constrainedMaxHeight, searchPlaceholder: this.parentNestedSelect.searchPlaceholder, optgroupLabel: this.label, selectAll: this.parentNestedSelect.selectAll, onOptionListAllSelected: () => this.wmOptgroupAllSelected.emit(), onOptionListAllDeselected: () => this.wmOptgroupAllDeselected.emit() }, h("slot", { key: '6ce3bf73ee05bbcddae0ebeca19be9bec51d66a3' })))));
     }
     static get is() { return "wm-optgroup"; }
     static get encapsulation() { return "shadow"; }
@@ -76,7 +127,13 @@ export class Optgroup {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Display name for this group, shown as the group button text in the\ndropdown menu."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "label",
@@ -93,7 +150,13 @@ export class Optgroup {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Controls whether this group's option panel is currently visible. Managed\nby the parent wm-nested-select \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "attribute": "is-expanded",
@@ -111,7 +174,13 @@ export class Optgroup {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Propagated from the parent wm-nested-select to configure the internal\noption list \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "attribute": "multiple",
@@ -129,7 +198,13 @@ export class Optgroup {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables this group, preventing the user from opening it or selecting any\nof its options."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -146,7 +221,10 @@ export class Optgroup {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the \"Select All\" button inside this group is activated."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -161,7 +239,10 @@ export class Optgroup {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the \"Deselect All\" button inside this group is activated."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -176,7 +257,13 @@ export class Optgroup {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals the parent wm-nested-select that this group's panel has opened \u2014\nnot for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -191,7 +278,13 @@ export class Optgroup {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals the parent wm-nested-select that this group's panel has closed,\ncarrying the group label so the parent can restore focus \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -217,7 +310,13 @@ export class Optgroup {
                 },
                 "docs": {
                     "text": "",
-                    "tags": []
+                    "tags": [{
+                            "name": "description",
+                            "text": "Programmatically deselects all options in this group by emitting\n`wmOptgroupAllDeselected`."
+                        }, {
+                            "name": "returns",
+                            "text": "`Promise<void>`"
+                        }]
                 }
             },
             "handleChildChange": {
@@ -234,7 +333,13 @@ export class Optgroup {
                 },
                 "docs": {
                     "text": "",
-                    "tags": []
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Notifies the internal option list that child options have changed so it can\nrefresh clone state \u2014 not for application use."
+                        }]
                 }
             }
         };