@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

@@ -1,4 +1,43 @@
 import { h, Host } from "@stencil/core";
+/**
+ * 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.
+ *
+ * @usageNotes
+ * - Text content is supplied as the element's text node (slot content). Do not nest other
+ *   elements inside wm-option.
+ * - Set the `selected` attribute/prop to pre-select an option on load.
+ * - In single-select mode, exactly one wm-option should be pre-selected (typically a
+ *   placeholder). In multi-select mode, zero or more options may be pre-selected.
+ * - The `value` prop is a pass-through convenience for application code to attach an
+ *   identifier; the component itself never reads or mutates it.
+ *
+ * @example {html} Basic option usage
+ * <wm-select label="Status">
+ *   <wm-option selected>Select a status</wm-option>
+ *   <wm-option value="active">Active</wm-option>
+ *   <wm-option value="inactive">Inactive</wm-option>
+ * </wm-select>
+ *
+ * @example {react} Basic option usage
+ * <WmSelect label="Status">
+ *   <WmOption selected={true}>Select a status</WmOption>
+ *   <WmOption value="active">Active</WmOption>
+ *   <WmOption value="inactive">Inactive</WmOption>
+ * </WmSelect>
+ *
+ * @example {html} Option with subinfo
+ * <wm-select label="User" multiple>
+ *   <wm-option subinfo="Biology dept">Alice</wm-option>
+ *   <wm-option subinfo="Chemistry dept">Bob</wm-option>
+ * </wm-select>
+ *
+ * @example {react} Option with subinfo
+ * <WmSelect label="User" multiple={true}>
+ *   <WmOption subinfo="Biology dept">Alice</WmOption>
+ *   <WmOption subinfo="Chemistry dept">Bob</WmOption>
+ * </WmSelect>
+ */
 export class Option {
     constructor() {
         this.value = undefined;
@@ -143,7 +182,7 @@ export class Option {
         this.parentOptionList.addEventListener("optionListSearchChanged", (ev) => this.handleSearch(ev));
     }
     render() {
-        return (h(Host, { key: 'bcabbcc25798f589af99a47142426ed517e1951f', role: "option", tabindex: this.focused ? 0 : -1, class: this.hostClasses }, h("div", { key: '83c81f098705c2ef5b6b2b374cc5d680ec78e2af', class: `option-wrapper ${this.parentOptionList.multiple ? "checkbox" : ""}` }, this.parentOptionList.multiple && (h("div", { key: '4cc738837041f134ef4d6ac1f541b8b0409813c6', class: `checkbox svg-icon ${this.selected ? "svg-checkbox-selected" : "svg-checkbox-blank"}` })), h("span", { key: '44b3d931ed548dc841033ebf4757eb400773a3a4', class: "option-text", "aria-hidden": "true", ref: (el) => (this.textEl = el) }, this.el.textContent), h("span", { key: '25a0ecb424a65a7d6c878ad65848ae5270ac563f', class: "sr-only" }, this.el.textContent)), h("div", { key: '4e25dd1f8e9ae5767123d136874ec1e40474c0fb', class: "subinfo" }, this.subinfo)));
+        return (h(Host, { key: 'aabc8b53087255c967031b5000d873d215bae9c1', role: "option", tabindex: this.focused ? 0 : -1, class: this.hostClasses }, h("div", { key: '5ec8d65e7bc71f5de40c4c43315a72942062cb6a', class: `option-wrapper ${this.parentOptionList.multiple ? "checkbox" : ""}` }, this.parentOptionList.multiple && (h("div", { key: 'eb32793019f0d541fd82e2c7378923b805ad3093', class: `checkbox svg-icon ${this.selected ? "svg-checkbox-selected" : "svg-checkbox-blank"}` })), h("span", { key: '9084254732da84361912aacf0bf9d7d7c0028811', class: "option-text", "aria-hidden": "true", ref: (el) => (this.textEl = el) }, this.el.textContent), h("span", { key: 'a9fe7e1a71473d958276dd4c897a9a125b5093ac', class: "sr-only" }, this.el.textContent)), h("div", { key: '54d8a8e9c2259e0134c3e91fe9c5932323a224f3', class: "subinfo" }, this.subinfo)));
     }
     static get is() { return "wm-option"; }
     static get encapsulation() { return "shadow"; }
@@ -170,7 +209,10 @@ export class Option {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Application-defined identifier for this option. The component never reads\nor modifies this value \u2014 it is purely a pass-through for application code to attach an ID\nor key."
+                        }],
                     "text": ""
                 },
                 "attribute": "value",
@@ -187,7 +229,10 @@ export class Option {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Secondary text displayed beneath the option label."
+                        }],
                     "text": ""
                 },
                 "attribute": "subinfo",
@@ -205,7 +250,13 @@ export class Option {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Prevents the option from being selected."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -223,7 +274,13 @@ export class Option {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Marks this option as currently selected."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "selected",
@@ -241,7 +298,13 @@ export class Option {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Programmatically focuses this option element when set to true. Managed by\nthe parent priv-option-list \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "attribute": "focused",
@@ -263,7 +326,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when this option is selected by the user."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "`HTMLWmOptionElement` \u2014 the option element that was selected."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -283,7 +352,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when this option is deselected by the user (multiselect mode only)."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "`HTMLWmOptionElement` \u2014 the option element that was deselected."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -303,7 +378,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Fires when a clone option is clicked so the parent can relay the selection\nto the original wm-option \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -323,7 +404,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals Arrow Up keydown to the parent option list for focus management \u2014\nnot for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -343,7 +430,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals Arrow Down keydown to the parent option list for focus management \u2014\nnot for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -363,7 +456,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals Arrow Left keydown to the parent wm-nested-select to navigate back\nto the group list \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -378,7 +477,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals Escape keydown to close the parent dropdown \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -398,7 +503,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals Home keydown to the parent option list to jump to the first option \u2014\nnot for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -418,7 +529,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals End keydown to the parent option list to jump to the last option \u2014\nnot for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -438,7 +555,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals Enter keydown for single-select close-on-confirm \u2014 not for\napplication use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -458,7 +581,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Signals a printable-character keydown to the parent option list for\njump-to-match navigation \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -478,7 +607,13 @@ export class Option {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Fires on blur so the parent can determine whether focus left the dropdown\nentirely \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {

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

@@ -2,6 +2,97 @@ import { h, Host } from "@stencil/core";
 import { forceUpdate } from "@stencil/core";
 import { getTextDir, toBool, handleDisabledAttribute, showTooltip, hideTooltip, debounce, findAllScrollableParents, } from "../../../global/functions";
 import { globalMessages, selectMessages } from "../../../global/intl";
+/**
+ * Dropdown list of options that allows single or multi-select. Functionally similar to the
+ * native HTML `<select>` element but with Ripple styling and richer features including
+ * multiselect, search filtering, and a Select All control. Composed of a parent wm-select
+ * element and wm-option children.
+ *
+ * @keyboardInteraction
+ * - **Closed button**: Space / Enter / Arrow Down opens the dropdown and focuses the first
+ *   option; Arrow Up opens and focuses the last option.
+ * - **Open dropdown**: Arrow Up / Down navigate options; Home / End jump to first / last;
+ *   typing a letter jumps to the first matching option.
+ * - **Single-select**: Enter / Space / click selects and closes.
+ * - **Multi-select**: Enter / Space / click toggles selection; Tab or Escape closes.
+ * - **Shift+Tab** (from options): Closes and returns focus to the trigger button.
+ *
+ * @accessibility
+ * - `label` is required even when `label-position` is `"none"` — it is used as the dropdown's
+ *   ARIA accessible name.
+ * - The dropdown renders with `role="listbox"`. Each wm-option renders with `role="option"`.
+ * - `required-field` renders a visible asterisk; the ARIA required constraint is communicated
+ *   via the label rather than `aria-required` because the listbox is in a sub-component.
+ * - Validation errors are announced via an `aria-live` region when `error-message` changes.
+ *
+ * @usageNotes
+ * - Single-select: always pre-select one option on load (e.g. a null-value first option). The
+ *   component warns in the console if no option is initially selected.
+ * - Multi-select: all options deselected on load is valid; use `placeholder` for that state.
+ * - `search` is best with 50 or fewer options — it filters by visible label text only.
+ * - `select-all` requires `multiple` to be set.
+ * - 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-select). `event.detail` is the `HTMLWmOptionElement`; read `.value` or
+ *   `.textContent` to get the selected value.
+ *
+ * @example {html} Single-select
+ * <wm-select label="Program">
+ *   <wm-option selected>Select a program</wm-option>
+ *   <wm-option>Biology</wm-option>
+ *   <wm-option>English</wm-option>
+ * </wm-select>
+ *
+ * @example {react} Single-select
+ * const [program, setProgram] = useState('');
+ *
+ * // event.detail is the selected HTMLWmOptionElement
+ * const handleSelect = (event) => {
+ *   setProgram(event.detail.value ?? event.detail.textContent);
+ * };
+ *
+ * <WmSelect label="Program" onWmOptionSelected={handleSelect}>
+ *   <WmOption selected>Select a program</WmOption>
+ *   <WmOption value="bio">Biology</WmOption>
+ *   <WmOption value="eng">English</WmOption>
+ * </WmSelect>
+ *
+ * @example {html} Multi-select with search and Select All
+ * <wm-select label="Programs" multiple search select-all
+ *   placeholder="Select programs">
+ *   <wm-option value="bio">Biology</wm-option>
+ *   <wm-option value="eng">English</wm-option>
+ * </wm-select>
+ *
+ * @example {react} Multi-select with search and 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));
+ * };
+ *
+ * <WmSelect
+ *   label="Programs"
+ *   multiple={true}
+ *   search={true}
+ *   selectAll={true}
+ *   placeholder="Select programs"
+ *   onWmOptionSelected={handleSelect}
+ *   onWmOptionDeselected={handleDeselect}
+ * >
+ *   <WmOption value="bio">Biology</WmOption>
+ *   <WmOption value="eng">English</WmOption>
+ * </WmSelect>
+ *
+ * @category Basic Controls
+ */
 export class Select {
     constructor() {
         this.scrollableParents = [];
@@ -323,14 +414,14 @@ export class Select {
     }
     render() {
         const showSubinfo = !this.multiple && this.selectedOptions.length > 0 && this.selectedOptions[0].subinfo;
-        return (h(Host, { key: '9a7eaa936f3f0723a852f780b706ce95dc83641a', onBlur: (ev) => this.handleComponentBlur(ev) }, h("div", { key: '4ab274d8cf13b0b8702928766bcaae20fa54216e', class: `wrapper ${getTextDir()} label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: '983713098202b6b9774ecabdbe56a43fe21f8938', class: "label-wrapper" }, h("label", { key: '8f79bf97083e3348ef10b15b8637e501915817b2', class: "label", id: "label", htmlFor: "selectbtn", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label), 
+        return (h(Host, { key: 'c54f6d584089fc988e1360b77063fb8019a4e61a', onBlur: (ev) => this.handleComponentBlur(ev) }, h("div", { key: '780d585f50bbc37adc27784195447ad958ac5fd0', class: `wrapper ${getTextDir()} label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: '3d58a763bd7b360d98259aad81f04c4a78e11dc7', class: "label-wrapper" }, h("label", { key: 'b8bde868d9ad20e57f75746421bb2aaa66b6a100', 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: 'f8fd8c444254d6588b010277684824a4f61bd0c7', class: "required" }, h("span", { key: '4bdbbded3292fa0a7d8ac7a7a14e63c4fa06a0bf', class: "sr-only" }, globalMessages.requiredField), h("span", { key: '6e28deddff56fc2009fdc7b7610c1f379b0e958a', "aria-hidden": "true" }, "*")))), h("div", { key: '47f1f1d2d62006f117d0be49bfccaaee71e91b76', class: "button-wrapper" }, h("button", { key: '9803fc04172c3c85241891b1abd5dedcc39d8db7', id: "selectbtn", disabled: this.isDisabled, "aria-labelledby": "label selectbtn", "aria-describedby": "info error", popoverTarget: "dropdown", popoverTargetAction: "toggle", class: "displayedoption", ref: (el) => (this.buttonEl = el) }, h("span", { key: 'e5a794d58c1115eaeabad64349aa763b880d8650', class: `overflowcontrol ${showSubinfo ? "hassubinfo" : ""}` }, h("span", { key: 'be25d6a9086a68305f23604395897d8ecb19af01', class: "button-text" }, this.setButtonText()), showSubinfo && h("span", { key: '09e34ec7ac74982b1f6c1db55b876d4a72256446', class: "subinfo" }, this.selectedOptions[0].subinfo)), h("div", { key: '75b86a8c694a6bb3e5e92744935242727d2233a7', class: `expand-icon svg-icon ${this.isExpanded ? "svg-expand-less" : "svg-expand-more"}` }), this.renderOverflowCount(), h("div", { key: '365885ab0546940f1ac4970894066beddf59ac42', ref: (el) => (this.measurementAreaEl = el), class: "measurement-area", "aria-hidden": "true" })), h("div", { key: 'fd952f83012203e7eaba6fcb8a83b053b5b17a28',
+        this.labelPosition !== "none" && this.requiredField && (h("span", { key: 'd1f5815114ed2e2b6d68f49641fd1a889e985756', class: "required" }, h("span", { key: '2c4a42286776c6338fdae10b951634cf1684da25', class: "sr-only" }, globalMessages.requiredField), h("span", { key: 'a74ae2aaf9eda4a2299b490c57454a72f9f260a7', "aria-hidden": "true" }, "*")))), h("div", { key: '93b51bbaa9ca04623e98c1af76860ea22bd4b72d', class: "button-wrapper" }, h("button", { key: 'b25dc16e18051bf99908293ccea902186ae35359', id: "selectbtn", disabled: this.isDisabled, "aria-labelledby": "label selectbtn", "aria-describedby": "info error", popoverTarget: "dropdown", popoverTargetAction: "toggle", class: "displayedoption", ref: (el) => (this.buttonEl = el) }, h("span", { key: '2f831cf2b13ac257c81707fdae93d7a9567945cf', class: `overflowcontrol ${showSubinfo ? "hassubinfo" : ""}` }, h("span", { key: '72020a439bc3ffa29304ee62ab028e2f12084cbe', class: "button-text" }, this.setButtonText()), showSubinfo && h("span", { key: 'cbdd0d38c80e9e08b877df058f498c838a991845', class: "subinfo" }, this.selectedOptions[0].subinfo)), h("div", { key: '131f48af6df1ac0e15d0e1e7156d478e57513304', class: `expand-icon svg-icon ${this.isExpanded ? "svg-expand-less" : "svg-expand-more"}` }), this.renderOverflowCount(), h("div", { key: '81a6bcdd69a1fb5a589dbb3962d48e935fc92e8d', ref: (el) => (this.measurementAreaEl = el), class: "measurement-area", "aria-hidden": "true" })), h("div", { key: 'e03cf5762c8be59a54f083ae4166651392d74c5f',
             // is-open is for the CSS transition in modern browsers
             // hidden is to wait for position calculations in Firefox
             class: `dropdown ${this.isExpanded ? "is-open" : ""} ${this.isHidden ? "hidden" : ""} ${this.openUp ? "upward" : ""}`, id: "dropdown", popover: "auto", ref: (el) => (this.dropdownEl = el),
             // @ts-ignore -- don't tell typescript but we're in the future
-            onToggle: (ev) => this.handleToggle(ev) }, h("priv-option-list", { key: '54216ae45b02cab8b403fe30f0c32814e5085f3a', ref: (el) => (this.optionListEl = el), multiple: this.multiple, search: this.search, selectAll: this.selectAll, maxHeight: this.maxHeight, searchPlaceholder: this.searchPlaceholder, onOptionListCloseRequested: () => {
+            onToggle: (ev) => this.handleToggle(ev) }, h("priv-option-list", { key: 'a5379ff676a5f5c0728b4fc37401c8a3057b9088', ref: (el) => (this.optionListEl = el), multiple: this.multiple, search: this.search, selectAll: this.selectAll, maxHeight: this.maxHeight, searchPlaceholder: this.searchPlaceholder, onOptionListCloseRequested: () => {
                 this.dropdownEl.hidePopover();
             }, onOptionListAllSelected: () => {
                 this.returnFocus = true;
@@ -338,7 +429,7 @@ export class Select {
             }, onOptionListAllDeselected: () => {
                 this.returnFocus = true;
                 this.wmSelectAllDeselected.emit();
-            } }, h("slot", { key: 'defde80bf2e3e435fccfda6b910a0d53f4df9989' }))), this.info && (h("div", { key: '464984b66832d1c978df56c53dc4099a671d75c5', class: "info" }, this.info)), h("div", { key: '3a63d5293c2c97f04bddc39a2fcf5181a245f2a3', id: "error", class: this.errorMessage ? "error-message" : "" }, this.errorMessage), h("div", { key: 'a9a47c2c45f0ab1149919504b9787378ccedc3de', id: "announcement", "aria-live": "polite", "aria-atomic": "true", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement)))));
+            } }, h("slot", { key: '0602b636a304dfb5b2c6514cd3d3baf1c8d8192e' }))), this.info && (h("div", { key: '1fdd831d0166c7553a5c7f16f6fa64f5fcaa25eb', class: "info" }, this.info)), h("div", { key: '9ac07d0fd62ce906e7d7a0aee87a42eb5e42cee6', id: "error", class: this.errorMessage ? "error-message" : "" }, this.errorMessage), h("div", { key: '5be4d3add955d50ccf5a89711402b1ba21e1050c', id: "announcement", "aria-live": "polite", "aria-atomic": "true", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement)))));
     }
     static get is() { return "wm-select"; }
     static get encapsulation() { return "shadow"; }
@@ -366,7 +457,13 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the entire select component, preventing all interaction."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -384,7 +481,13 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Overrides the maximum height of the options list. Accepts any valid CSS\nlength value (e.g. `\"20rem\"`, `\"300px\"`)."
+                        }, {
+                            "name": "default",
+                            "text": "\"200px\""
+                        }],
                     "text": ""
                 },
                 "attribute": "max-height",
@@ -402,7 +505,13 @@ export class Select {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible label for the dropdown. Required even when `label-position` is\n`\"none\"` \u2014 used as the ARIA accessible name."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "label",
@@ -419,7 +528,13 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Position of the label relative to the dropdown button. `\"none\"` hides the\nlabel visually but keeps it accessible via ARIA."
+                        }, {
+                            "name": "default",
+                            "text": "\"top\""
+                        }],
                     "text": ""
                 },
                 "attribute": "label-position",
@@ -437,7 +552,13 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Displays a required-field asterisk (*) next to the label."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "required-field",
@@ -455,7 +576,10 @@ export class Select {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Puts the component in an error state and displays this message beneath the\ntrigger button. Use for form validation feedback."
+                        }],
                     "text": ""
                 },
                 "attribute": "error-message",
@@ -472,7 +596,13 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Enables multiselect mode, allowing more than one option to be selected\nsimultaneously."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "multiple",
@@ -490,7 +620,13 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Adds a search input inside the dropdown that filters visible options by label\ntext. Compatible with both single and multiselect modes. Best with 50 or fewer options."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "search",
@@ -508,7 +644,13 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Adds a \"Select All\" / \"Deselect All\" toggle at the top of the dropdown.\nHas no effect unless `multiple` is also set."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "select-all",
@@ -526,7 +668,10 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Text displayed in the trigger button in multiselect mode when no options are\nselected. Not applicable in single-select mode \u2014 use a null-value first option instead."
+                        }],
                     "text": ""
                 },
                 "attribute": "placeholder",
@@ -544,7 +689,10 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Placeholder text displayed inside the search input when `search` is enabled."
+                        }],
                     "text": ""
                 },
                 "attribute": "search-placeholder",
@@ -562,7 +710,10 @@ export class Select {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Text displayed in the trigger button in multiselect mode when every option\nis selected."
+                        }],
                     "text": ""
                 },
                 "attribute": "all-selected-message",
@@ -580,7 +731,10 @@ export class Select {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Informational hint text rendered beneath the dropdown button. Use for\nsupporting instructions or constraints."
+                        }],
                     "text": ""
                 },
                 "attribute": "info",
@@ -604,7 +758,10 @@ export class Select {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires after the component has finished loading and is ready for interaction.\nUse this to read initial selection state or call methods."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -619,7 +776,10 @@ export class Select {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when focus leaves the component entirely (not when moving between\nthe trigger and an option within the dropdown)."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -634,7 +794,10 @@ export class Select {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks \"Select All\" in multiselect mode and all options\nbecome selected."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -649,7 +812,10 @@ export class Select {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks \"Deselect All\" in multiselect mode and all\noptions become deselected."
+                        }],
                     "text": ""
                 },
                 "complexType": {