@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,878 @@
+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.
+ *
+ * @category Basic Controls
+ *
+ * @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: has no `placeholder` prop — a selection must always be present, and the
+ *   component warns in the console if no option is initially selected. Since there's no way
+ *   to distinguish "the user selected the first option" from "no selection was made," use a
+ *   null-value first option to represent the unselected state and keep the component
+ *   revertible to "no option chosen." That option must not be disabled, and for
+ *   accessibility/consistency its label should be limited to "None", "Select an option", or
+ *   "--".
+ * - 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>
+ *
+ */
+export class Select {
+    constructor() {
+        this.scrollableParents = [];
+        this.returnFocus = false;
+        this.hasAnchor = CSS.supports("top", "anchor(bottom)"); // for FF polyfill
+        this.displayedOptions = [];
+        this.debouncedReposition = debounce(() => {
+            this.dropdownPosition();
+        }, 100);
+        this.disabled = false;
+        this.maxHeight = "200px";
+        this.label = undefined;
+        this.labelPosition = "top";
+        this.requiredField = false;
+        this.errorMessage = undefined;
+        this.multiple = false;
+        this.search = false;
+        this.selectAll = false;
+        this.placeholder = selectMessages.multiPlaceholder;
+        this.searchPlaceholder = selectMessages.searchPlaceholder;
+        this.allSelectedMessage = selectMessages.allSelected;
+        this.info = undefined;
+        this.isExpanded = false;
+        this.isHidden = false;
+        this.openUp = false;
+        this.announcement = "";
+    }
+    get childOptions() {
+        return Array.from(this.el.querySelectorAll("wm-option"));
+    }
+    get isDisabled() {
+        // string "false" needs to be treated as bool False because react wrappers convert bool to string.
+        return toBool(this.disabled);
+    }
+    get displayText() {
+        return this.displayedOptions.map((x) => x.textContent).join(", ");
+    }
+    get selectedOptions() {
+        return Array.from(this.el.querySelectorAll("wm-option")).filter((x) => x.selected);
+    }
+    get allSelected() {
+        return this.childOptions.every((option) => option.selected);
+    }
+    //////////////////////////////////////
+    handleOptionSelection() {
+        if (!this.multiple) {
+            this.returnFocus = true;
+            this.dropdownEl.hidePopover();
+        }
+    }
+    handleChildEnter() {
+        // only occurs for multiselects. handle the click, then close
+        this.returnFocus = true;
+        this.dropdownEl.hidePopover();
+    }
+    closeDropdownOnEscape() {
+        this.returnFocus = true;
+        this.dropdownEl.hidePopover();
+    }
+    handleToggle(ev) {
+        ev.newState === "open" ? this.onOpen() : this.onClose();
+    }
+    dropdownPosition() {
+        // polyfill for opening up or down + positioning according to screen
+        // (must recalculate on scroll, resize)
+        // Using transform for better performance - only affects composite layer, no layout recalculation
+        const buttonElRect = this.buttonEl.getBoundingClientRect();
+        const spaceAbove = buttonElRect.top;
+        const spaceBelow = document.documentElement.clientHeight - buttonElRect.bottom;
+        const dropdownHeight = this.dropdownEl.clientHeight;
+        // Clear any previously set positioning properties
+        this.el.style.removeProperty("--dropdown-translate-y");
+        this.el.style.removeProperty("--dropdown-max-height");
+        this.el.style.removeProperty("--dropdown-left");
+        // Set horizontal position and width to match button
+        this.el.style.setProperty("--dropdown-left", buttonElRect.left + "px");
+        this.el.style.setProperty("--button-width", buttonElRect.width + "px");
+        if (dropdownHeight <= spaceBelow) {
+            // Case 1: Enough space below - position dropdown below the button
+            this.el.style.setProperty("--dropdown-translate-y", buttonElRect.bottom + "px");
+        }
+        else if (dropdownHeight <= spaceAbove) {
+            // Case 2: Not enough space below, but enough above - position dropdown above the button
+            this.el.style.setProperty("--dropdown-translate-y", buttonElRect.top - dropdownHeight + "px");
+        }
+        else {
+            // Case 3: Not enough space in either direction - use the larger available space and constrain height
+            if (spaceBelow >= spaceAbove) {
+                // Use space below and constrain dropdown height
+                this.el.style.setProperty("--dropdown-translate-y", buttonElRect.bottom + "px");
+                this.el.style.setProperty("--dropdown-max-height", spaceBelow + "px");
+            }
+            else {
+                // Use space above and constrain dropdown height
+                this.el.style.setProperty("--dropdown-translate-y", "0px");
+                this.el.style.setProperty("--dropdown-max-height", spaceAbove + "px");
+            }
+        }
+        this.isHidden = false;
+    }
+    onOpen() {
+        if (!this.isExpanded && !this.isDisabled) {
+            // polyfill for browsers without anchor() support (FF)
+            if (!this.hasAnchor) {
+                this.dropdownPosition();
+            }
+            requestAnimationFrame(() => {
+                const anchorRect = this.buttonEl.getBoundingClientRect();
+                const hasSpaceBelow = this.dropdownEl.offsetHeight <= document.documentElement.clientHeight - anchorRect.bottom;
+                const hasSpaceAbove = this.dropdownEl.offsetHeight <= anchorRect.top;
+                this.openUp = !hasSpaceBelow && hasSpaceAbove;
+                if (!hasSpaceBelow && !hasSpaceAbove) {
+                    // dropdown will open downwards but doesn't have enough space
+                    // it needs to be absolutely positioned + html has to have overflow-y auto
+                    // (the default, but could have been overriden)
+                    // in order to ensure the options can be scrolled to
+                    // (would already be possible if the page has content below. this is in case select was at bottom of page)
+                    this.initialHtmlOverflowY = document.documentElement.style.overflowY;
+                    document.documentElement.style.overflowY = "auto";
+                    this.dropdownEl.style.position = "absolute";
+                }
+                this.isExpanded = true;
+            });
+            setTimeout(() => {
+                // focusing doesn't work when within requestAnimationFrame
+                this.optionListEl.handleInitialFocus(this.elToFocus);
+                this.elToFocus = undefined;
+            }, 50);
+        }
+    }
+    onClose() {
+        if (this.isExpanded) {
+            this.optionListEl.unfocusAll();
+            // see onOpen
+            document.documentElement.style.overflowY = this.initialHtmlOverflowY || "";
+            this.dropdownEl.style.position = "fixed";
+            window.setTimeout(() => {
+                if (!this.hasAnchor) {
+                    this.isHidden = true;
+                }
+                if (this.optionListEl.multiple) {
+                    this.optionListEl.updateOptionVisibility();
+                }
+                // clear search field, reset filtered / bolded state of wm-options
+                if (this.search) {
+                    this.optionListEl.clearSearch();
+                }
+                this.isExpanded = false;
+            }, 150);
+            if (this.returnFocus) {
+                requestAnimationFrame(() => {
+                    this.buttonEl.focus();
+                    this.returnFocus = false;
+                });
+            }
+        }
+    }
+    handleKey(ev) {
+        switch (ev.key) {
+            case "Tab":
+                // if tabbing backwards, close and return focus to button. Otherwise, close but do not redirect focus.
+                if (this.isExpanded && ev.shiftKey) {
+                    this.returnFocus = true;
+                }
+                this.dropdownEl.hidePopover();
+                break;
+            case "ArrowDown":
+                if (this.isExpanded === false) {
+                    ev.preventDefault();
+                    this.elToFocus = "next";
+                    this.dropdownEl.showPopover();
+                }
+                break;
+            case "ArrowUp":
+                if (this.isExpanded === false) {
+                    ev.preventDefault();
+                    this.elToFocus = "previous";
+                    this.dropdownEl.showPopover();
+                }
+                break;
+        }
+    }
+    handleResize() {
+        if (!this.hasAnchor && this.isExpanded) {
+            this.isHidden = true;
+            this.debouncedReposition();
+        }
+    }
+    handleScroll() {
+        if (this.isExpanded) {
+            this.isHidden = true;
+            this.debouncedReposition();
+        }
+    }
+    componentWillLoad() {
+        if (!this.hasAnchor) {
+            // Start hidden to prevent flash on first load
+            this.isHidden = true;
+        }
+        if (!this.label) {
+            console.error("For accessibility purposes, this component requires a label (even if `label-position` is set to `none`).");
+        }
+        if (!this.multiple && this.selectedOptions.length === 0) {
+            console.error("wm-select should have one initial option selected");
+        }
+        handleDisabledAttribute(this.el, this.isDisabled);
+        const mutationObserver = new MutationObserver((mutationRecordList) => mutationRecordList.forEach((_mutationRecord) => this.handleChildChange()));
+        mutationObserver.observe(this.el, {
+            childList: true,
+            attributes: true,
+            subtree: true,
+            attributeFilter: ["selected"],
+        });
+    }
+    handleChildChange() {
+        forceUpdate(this.el);
+        if (this.multiple) {
+            // update state of clone options
+            this.optionListEl.handleChildChange();
+        }
+    }
+    componentDidLoad() {
+        this.wmSelectDidLoad.emit();
+        if (!this.hasAnchor) {
+            this.scrollableParents = findAllScrollableParents(this.el);
+            // Add scroll listeners to all scrollable parents
+            this.scrollableParents.forEach((parent) => {
+                if (parent === document.documentElement) {
+                    // For document element, listen to window scroll event
+                    window.addEventListener("scroll", () => this.handleScroll());
+                }
+                else {
+                    // For regular elements, listen to their scroll event
+                    parent.addEventListener("scroll", () => this.handleScroll());
+                }
+            });
+        }
+    }
+    announceError() {
+        if (this.errorMessage) {
+            setTimeout(() => this.announce(this.errorMessage), 100);
+        }
+    }
+    handleDisabledChange() {
+        handleDisabledAttribute(this.el, this.isDisabled);
+    }
+    handleComponentBlur(ev) {
+        // Do not close or emit custom blur event when blurring to an element inside (wm-option)
+        if (!this.el.contains(ev.relatedTarget)) {
+            this.wmSelectBlurred.emit();
+        }
+    }
+    handleLabelMouseEnter(ev) {
+        const labelEl = ev.target;
+        if (labelEl.scrollWidth > labelEl.clientWidth) {
+            showTooltip("right", ev.target, this.label);
+        }
+    }
+    announce(message) {
+        // \u00A0 is a non-breaking space character, which causes the message to be read as a new one
+        if (this.liveRegionEl.textContent === message) {
+            message += "\u00A0";
+        }
+        this.announcement = message;
+    }
+    handleOverflow() {
+        if (!this.buttonEl) {
+            forceUpdate(this.el);
+        }
+        else {
+            // handle overflow + counter for multiselect
+            // this is a fixed measurement accounting for the max width of a 3 character overflow counter
+            const overflowCounterWidth = 38;
+            const computedStyle = window.getComputedStyle(this.buttonEl);
+            // there seems to be no quick way to get an elements width without padding, except for subtracting padding manually
+            const paddingLeft = parseInt(computedStyle.getPropertyValue("padding-left").slice(0, -2));
+            const paddingRight = parseInt(computedStyle.getPropertyValue("padding-right").slice(0, -2));
+            const availableSpace = this.buttonEl.clientWidth - paddingLeft - paddingRight - overflowCounterWidth;
+            this.overflowCount = 0;
+            this.measurementAreaEl.textContent = this.displayText;
+            let optionsTotalWidth = this.measurementAreaEl.clientWidth;
+            while (optionsTotalWidth > availableSpace && this.displayedOptions.length > 1) {
+                this.overflowCount++;
+                this.displayedOptions.pop();
+                this.measurementAreaEl.textContent = this.displayText;
+                optionsTotalWidth = this.measurementAreaEl.clientWidth;
+            }
+        }
+    }
+    setButtonText() {
+        if (!this.multiple) {
+            const selEl = this.childOptions.filter((x) => x.selected)[0];
+            return selEl ? selEl.textContent : "";
+        }
+        this.displayedOptions = this.childOptions.filter((x) => x.selected);
+        const noDisplayedOptions = this.displayedOptions.length < 1;
+        if (noDisplayedOptions) {
+            this.overflowCount = 0;
+            return this.placeholder;
+        }
+        this.handleOverflow();
+        if (this.allSelected) {
+            // Consolidated label when every option is selected; do not show the +N overflow badge.
+            // On first render, handleOverflow may not have measured yet; we still show this message.
+            this.overflowCount = 0;
+            this.buttonText = this.allSelectedMessage;
+        }
+        else {
+            // otherwise, if handleOverflow was able to calculate, it set the count and the display text
+            // if it wasn't able to calculate, the text of all the selected options will be displayed and may truncate (acceptable as fallback)
+            this.buttonText = this.displayText;
+        }
+        return this.buttonText; // multiselect value
+    }
+    renderOverflowCount() {
+        if (this.overflowCount > 0) {
+            return (h("span", null, h("span", { class: "overflow-counter" }, "+", this.overflowCount)));
+        }
+    }
+    render() {
+        const showRequired = this.labelPosition !== "none" && this.requiredField;
+        return (h(Host, { key: 'f70c523818ecb070061c5750ddd793b4375ca7d7', onBlur: (ev) => this.handleComponentBlur(ev) }, h("div", { key: '2f648b5082ffa541ed1c3d72ef1b5ebb161ea15c', class: `wrapper ${getTextDir()} label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: '83e582f81d749205d72ef33851bb60e471e4b859', class: "label-wrapper" }, h("label", { key: '21c8583c1f5510ed2f93094ef0d22898e298728c', 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;
+        // instead the sr-only text is included in the button's aria-labelledby below
+        showRequired && (h("span", { key: '6510b0db8f404b00c5a95b0996aac71917c1ab77', class: "required" }, h("span", { key: 'e39f5c4d7f7b432d4c3b9ff9177cf0dc0a416bb7', class: "sr-only", id: "required" }, globalMessages.requiredField), h("span", { key: '8b3c8e2c934e1faca6db74eaa9b953dad40f3570', "aria-hidden": "true" }, "*")))), h("div", { key: '74a055700ee1622c263206b45a52d19f57648807', class: "button-wrapper" }, h("button", { key: '84cb7ca0dfcb742b34fbf107e59a4859709ba7d1', id: "selectbtn", disabled: this.isDisabled, "aria-labelledby": showRequired ? "label required selectbtn" : "label selectbtn", "aria-describedby": "info error", popoverTarget: "dropdown", popoverTargetAction: "toggle", class: "displayedoption", ref: (el) => (this.buttonEl = el) }, h("span", { key: '03b78ab8e7ea097f344e5d1947387cce6b5f4d27', class: "overflowcontrol" }, h("span", { key: '675ce4e5931d8822e62d8c7eabfda07759ee8720', class: "button-text" }, this.setButtonText())), h("div", { key: '5da2f36c2438cb96a721c6f6e9412ef95a40ef03', class: `expand-icon svg-icon ${this.isExpanded ? "svg-expand-less" : "svg-expand-more"}` }), this.renderOverflowCount(), h("div", { key: '3e9f1140bee3f6825a5b3b10958f446d1b3adb41', ref: (el) => (this.measurementAreaEl = el), class: "measurement-area", "aria-hidden": "true" })), h("div", { key: '17f3c905ba01331b738e322b02cbb0f9789bff7b',
+            // 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: '99d213da0ba3cd67dfa3da56ed16bbcad18e4cb6', 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;
+                this.wmSelectAllSelected.emit();
+            }, onOptionListAllDeselected: () => {
+                this.returnFocus = true;
+                this.wmSelectAllDeselected.emit();
+            } }, h("slot", { key: '989c9f0a96cc70227c497c0cb00cd0104cd71015' }))), this.info && h("div", { key: '184f9893590c433fd0eac7c9d5972dcd6980f31a', class: "info" }, this.info), h("div", { key: '0937d79b083c116e911f0cd5fefc1f6d801ffe95', id: "error", class: this.errorMessage ? "error-message" : "" }, this.errorMessage), h("div", { key: '07e61a5651ef082e844d1e74b2bb4174de5b4abf', 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"; }
+    static get delegatesFocus() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-select.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-select.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the entire select component, preventing all interaction."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "disabled",
+                "reflect": true,
+                "defaultValue": "false"
+            },
+            "maxHeight": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "\"200px\""
+            },
+            "label": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "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",
+                "reflect": false
+            },
+            "labelPosition": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"top\" | \"left\" | \"none\"",
+                    "resolved": "\"left\" | \"none\" | \"top\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "\"top\""
+            },
+            "requiredField": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Displays a required-field asterisk (*) next to the label."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "required-field",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "errorMessage": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "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",
+                "reflect": false
+            },
+            "multiple": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Enables multiselect mode, allowing more than one option to be selected\nsimultaneously."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "multiple",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "search": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "selectAll": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "placeholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "selectMessages.multiPlaceholder"
+            },
+            "searchPlaceholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Placeholder text displayed inside the search input when `search` is enabled."
+                        }],
+                    "text": ""
+                },
+                "attribute": "search-placeholder",
+                "reflect": false,
+                "defaultValue": "selectMessages.searchPlaceholder"
+            },
+            "allSelectedMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Text displayed in the trigger button in multiselect mode when every option\nis selected."
+                        }],
+                    "text": ""
+                },
+                "attribute": "all-selected-message",
+                "reflect": false,
+                "defaultValue": "selectMessages.allSelected"
+            },
+            "info": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Informational hint text rendered beneath the dropdown button. Use for\nsupporting instructions or constraints."
+                        }],
+                    "text": ""
+                },
+                "attribute": "info",
+                "reflect": false
+            }
+        };
+    }
+    static get states() {
+        return {
+            "isExpanded": {},
+            "isHidden": {},
+            "openUp": {},
+            "announcement": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "wmSelectDidLoad",
+                "name": "wmSelectDidLoad",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "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": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "wmSelectBlurred",
+                "name": "wmSelectBlurred",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "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": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "wmSelectAllSelected",
+                "name": "wmSelectAllSelected",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks \"Select All\" in multiselect mode and all options\nbecome selected."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }, {
+                "method": "wmSelectAllDeselected",
+                "name": "wmSelectAllDeselected",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks \"Deselect All\" in multiselect mode and all\noptions become deselected."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "errorMessage",
+                "methodName": "announceError"
+            }, {
+                "propName": "disabled",
+                "methodName": "handleDisabledChange"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "wmOptionSelected",
+                "method": "handleOptionSelection",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "wmEnterKeyPressed",
+                "method": "handleChildEnter",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "wmEscKeyPressed",
+                "method": "closeDropdownOnEscape",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "keydown",
+                "method": "handleKey",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "resize",
+                "method": "handleResize",
+                "target": "window",
+                "capture": false,
+                "passive": true
+            }];
+    }
+}