@keenmate/web-multiselect 2.0.1 → 2.2.0-rc01

package/vscode.html-custom-data.json

@@ -4,7 +4,7 @@
   "tags": [
     {
       "name": "web-multiselect",
-      "description": "\n---\n\n\n### **Events:**\n - **select** - An option was selected. `detail.option` is the selected option; `detail.selectedOptions`/`detail.selectedValues` are the full selection.\n- **deselect** - An option was removed from the selection. `detail.option` is that option.\n- **change** - The selection changed. `detail.selectedOptions`/`detail.selectedValues` are the full selection.\n- **add** - The user chose to create a new option from the typed text (via the \"add new\" prompt or Enter) — requires `allow-add-new`. `detail.value` is the typed text; `detail.option` is the created item when `addNewCallback` produced one.\n\n### **Methods:**\n - **formResetCallback(): _void_** - Called by the browser when the surrounding <form> is reset. Clears the\r\npicker's selection so the control participates in the standard reset.\n\n\n\n\n\n\n\n- **showMessage(content: _string | HTMLElement_, opts: _MessageOptions_): _void_** - Surface a transient message (\"toast\") on top of the component — visible even in the\r\nfullscreen overlay, where page-level UI is hidden behind the sheet. Content is text or\r\nan element; `opts.variant` sets the tone and `opts.duration` the auto-dismiss (0 =\r\nsticky). Also reached automatically when a `beforeSelect`/`beforeDeselect` callback\r\nreturns a reason string.\n- **hideMessage(): _void_** - Dismiss the transient message shown by showMessage, if any.\n- **clearSearch(): _void_** - Clear the search box and restore the full option list (does not touch the selection — use\r\nclearAll for that). Pair with scrollToValue to reveal then scroll to an option\r\na search had filtered out: `el.clearSearch(); el.scrollToValue(v)`.\n- **search(term: _string_): _void_** - Programmatically set the search text and filter, as if the user typed it (runs\r\n`beforeSearchCallback` / `minSearchLength` / async `searchCallback`). Does not open the dropdown\r\n— call open if you want it visible. Pass `''` to clear (same as clearSearch).\n- **scrollToIndex(index: _number_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll the open dropdown to the option at `index` (into the current filtered list). Returns\r\nfalse if closed or out of range. Deferred internally so `el.open(); el.scrollToIndex(i)` works.\n- **scrollToValue(value: _string | number_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll the open dropdown to the option with this `value`. Returns false if it isn't in the\r\ncurrently visible list (filtered out by search, or under a collapsed tree branch) — call\r\nclearSearch / expand first.\n- **scrollToGroup(name: _string_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll to a group: its header in standard rendering, or the group's first option in\r\nvirtual-scroll mode (no headers there). Returns false in tree mode or if the group is empty\r\nin the current filtered list.\n- **open(): _void_** - Open the dropdown.\n- **close(): _void_** - Close the dropdown.\n- **toggle(): _void_** - Toggle the dropdown open/closed.\n\n### **CSS Properties:**\n - **--ms-rem** - Base sizing unit for proportional scaling (default: 10px) _(default: undefined)_\n- **--ms-accent-color** - Primary accent color _(default: undefined)_\n- **--ms-accent-color-hover** - Accent color on hover _(default: undefined)_\n- **--ms-accent-color-active** - Accent color when pressed _(default: undefined)_\n- **--ms-accent-color-light** - Light accent background _(default: undefined)_\n- **--ms-accent-color-light-hover** - Light accent hover _(default: undefined)_\n- **--ms-text-color-1** - Primary text color _(default: undefined)_\n- **--ms-text-color-2** - Secondary text color _(default: undefined)_\n- **--ms-text-color-3** - Tertiary text color _(default: undefined)_\n- **--ms-text-color-4** - Quaternary text color _(default: undefined)_\n- **--ms-text-color-on-accent** - Text on accent backgrounds _(default: undefined)_\n- **--ms-text-primary** - Legacy alias for text-color-1 _(default: undefined)_\n- **--ms-text-secondary** - Legacy alias for text-color-3 _(default: undefined)_\n- **--ms-primary-bg** - Hover/focus background (options, action buttons, counter); reads --base-hover-bg _(default: undefined)_\n- **--ms-primary-bg-hover** - Active/stronger background (counter badge text); reads --base-active-bg _(default: undefined)_\n- **--ms-border-color** - Default border color _(default: undefined)_\n- **--ms-border** - Full border shorthand _(default: undefined)_\n- **--ms-input-bg** - Input field background _(default: undefined)_\n- **--ms-input-color** - Input text color _(default: undefined)_\n- **--ms-input-border** - Input border _(default: undefined)_\n- **--ms-input-border-hover** - Input border on hover _(default: undefined)_\n- **--ms-input-border-focus** - Input border when focused _(default: undefined)_\n- **--ms-input-placeholder-color** - Placeholder text color _(default: undefined)_\n- **--ms-input-bg-disabled** - Disabled input background _(default: undefined)_\n- **--ms-input-height** - Input height _(default: undefined)_\n- **--ms-input-font-size** - Input font size _(default: undefined)_\n- **--ms-input-border-width** - Input border width _(default: undefined)_\n- **--ms-input-border-radius** - Input border radius _(default: undefined)_\n- **--ms-input-text** - Input text color _(default: undefined)_\n- **--ms-toggle-color** - Toggle icon color _(default: undefined)_\n- **--ms-toggle-icon-color** - Toggle icon color (semantic) _(default: undefined)_\n- **--ms-toggle-icon-color-open** - Toggle icon color when open _(default: undefined)_\n- **--ms-counter-padding** - Counter badge padding _(default: undefined)_\n- **--ms-counter-bg** - Counter badge background _(default: undefined)_\n- **--ms-counter-color** - Counter badge text color _(default: undefined)_\n- **--ms-counter-font-size** - Counter badge font size _(default: undefined)_\n- **--ms-counter-font-weight** - Counter badge font weight _(default: undefined)_\n- **--ms-counter-border-radius** - Counter badge border radius _(default: undefined)_\n- **--ms-counter-bg-hover** - Counter badge hover background _(default: undefined)_\n- **--ms-counter-badge-bg** - Counter badge semantic background _(default: undefined)_\n- **--ms-counter-badge-bg-hover** - Counter badge semantic hover _(default: undefined)_\n- **--ms-counter-badge-color** - Counter badge semantic color _(default: undefined)_\n- **--ms-hint-padding** - Floating hint padding _(default: undefined)_\n- **--ms-hint-border** - Floating hint border _(default: undefined)_\n- **--ms-hint-border-radius** - Floating hint border radius _(default: undefined)_\n- **--ms-hint-box-shadow** - Floating hint shadow _(default: undefined)_\n- **--ms-hint-font-size** - Floating hint font size _(default: undefined)_\n- **--ms-hint-bg** - Floating hint background _(default: undefined)_\n- **--ms-hint-color** - Floating hint text color _(default: undefined)_\n- **--ms-hint-border-color** - Floating hint border color _(default: undefined)_\n- **--ms-dropdown-bg** - Dropdown background _(default: undefined)_\n- **--ms-dropdown-text-color** - Dropdown text color _(default: undefined)_\n- **--ms-dropdown-border** - Dropdown border _(default: undefined)_\n- **--ms-dropdown-border-color** - Dropdown border color _(default: undefined)_\n- **--ms-dropdown-border-radius** - Dropdown border radius _(default: undefined)_\n- **--ms-dropdown-box-shadow** - Dropdown shadow _(default: undefined)_\n- **--ms-dropdown-box-shadow-semantic** - Dropdown semantic shadow _(default: undefined)_\n- **--ms-dropdown-width** - Options dropdown width (defaults to the input width; also set via the dropdown-width attribute) _(default: undefined)_\n- **--ms-options-max-height** - Options list max height _(default: undefined)_\n- **--ms-z-index-dropdown** - Dropdown z-index _(default: undefined)_\n- **--ms-z-index-sticky** - Sticky elements z-index _(default: undefined)_\n- **--ms-actions-gap** - Actions row gap _(default: undefined)_\n- **--ms-actions-padding** - Actions row padding _(default: undefined)_\n- **--ms-actions-border-bottom** - Actions row border _(default: undefined)_\n- **--ms-actions-bg** - Actions row background _(default: undefined)_\n- **--ms-actions-border-color** - Actions row border color _(default: undefined)_\n- **--ms-action-btn-padding** - Action button padding _(default: undefined)_\n- **--ms-action-btn-font-size** - Action button font size _(default: undefined)_\n- **--ms-action-btn-border** - Action button border _(default: undefined)_\n- **--ms-action-btn-border-radius** - Action button border radius _(default: undefined)_\n- **--ms-action-btn-bg** - Action button background _(default: undefined)_\n- **--ms-action-btn-color** - Action button color _(default: undefined)_\n- **--ms-action-btn-bg-hover** - Action button hover background _(default: undefined)_\n- **--ms-action-btn-border-color-hover** - Action button hover border _(default: undefined)_\n- **--ms-action-button-bg** - Semantic action button background _(default: undefined)_\n- **--ms-action-button-bg-hover** - Semantic action button hover _(default: undefined)_\n- **--ms-action-button-border-color** - Semantic action button border _(default: undefined)_\n- **--ms-action-button-border-color-hover** - Semantic action button hover border _(default: undefined)_\n- **--ms-action-button-color** - Semantic action button color _(default: undefined)_\n- **--ms-options-padding** - Options container padding _(default: undefined)_\n- **--ms-group-border-top** - Group border top _(default: undefined)_\n- **--ms-group-margin-top** - Group margin top _(default: undefined)_\n- **--ms-group-padding-top** - Group padding top _(default: undefined)_\n- **--ms-group-border-color** - Group border color _(default: undefined)_\n- **--ms-group-label-padding** - Group label padding _(default: undefined)_\n- **--ms-group-label-font-size** - Group label font size _(default: undefined)_\n- **--ms-group-label-font-weight** - Group label font weight _(default: undefined)_\n- **--ms-group-label-color** - Group label color _(default: undefined)_\n- **--ms-group-label-transform** - Group label text transform _(default: undefined)_\n- **--ms-group-label-letter-spacing** - Group label letter spacing _(default: undefined)_\n- **--ms-option-gap** - Option content gap _(default: undefined)_\n- **--ms-option-padding** - Option padding _(default: undefined)_\n- **--ms-option-padding-h** - Option horizontal padding _(default: undefined)_\n- **--ms-option-color** - Option text color _(default: undefined)_\n- **--ms-option-bg** - Option background _(default: undefined)_\n- **--ms-option-bg-hover** - Option hover background _(default: undefined)_\n- **--ms-option-bg-focused** - Option focused background _(default: undefined)_\n- **--ms-option-outline-focused** - Option focus outline _(default: undefined)_\n- **--ms-option-focus-outline-offset** - Option focus outline offset _(default: undefined)_\n- **--ms-option-bg-matched** - Matched option background _(default: undefined)_\n- **--ms-option-border-matched** - Matched option border _(default: undefined)_\n- **--ms-option-bg-selected** - Selected option background _(default: undefined)_\n- **--ms-option-text-color** - Option text color (semantic) _(default: undefined)_\n- **--ms-option-color-hover** - Option hover color _(default: undefined)_\n- **--ms-option-color-focused** - Option focused color _(default: undefined)_\n- **--ms-option-outline-color-focused** - Option focus outline color _(default: undefined)_\n- **--ms-option-color-matched** - Matched option color _(default: undefined)_\n- **--ms-option-border-matched-color** - Matched option border color _(default: undefined)_\n- **--ms-option-bg-focused-hover** - Focused option hover background _(default: undefined)_\n- **--ms-option-bg-matched-hover** - Matched option hover background _(default: undefined)_\n- **--ms-option-bg-selected-focused** - Selected focused background _(default: undefined)_\n- **--ms-option-bg-selected-matched** - Selected matched background _(default: undefined)_\n- **--ms-option-disabled-bg** - Disabled option background _(default: undefined)_\n- **--ms-option-bg-disabled-selected** - Disabled selected background _(default: undefined)_\n- **--ms-disabled-opacity** - Disabled option opacity _(default: undefined)_\n- **--ms-option-content-gap** - Option content gap _(default: undefined)_\n- **--ms-option-icon-size** - Option icon size _(default: undefined)_\n- **--ms-option-icon-font-size** - Option icon font size _(default: undefined)_\n- **--ms-option-title-font-size** - Option title font size _(default: undefined)_\n- **--ms-option-title-color** - Option title color _(default: undefined)_\n- **--ms-option-subtitle-margin-top** - Option subtitle margin _(default: undefined)_\n- **--ms-option-subtitle-font-size** - Option subtitle font size _(default: undefined)_\n- **--ms-option-subtitle-line-height** - Option subtitle line height _(default: undefined)_\n- **--ms-option-subtitle-color** - Option subtitle color _(default: undefined)_\n- **--ms-option-mark-bg** - Search match highlight background _(default: undefined)_\n- **--ms-option-mark-color** - Search match highlight color _(default: undefined)_\n- **--ms-option-mark-font-weight** - Search match highlight weight _(default: undefined)_\n- **--ms-checkbox-margin-top** - Checkbox margin top _(default: undefined)_\n- **--ms-checkbox-margin-right** - Checkbox margin right _(default: undefined)_\n- **--ms-checkbox-margin-bottom** - Checkbox margin bottom _(default: undefined)_\n- **--ms-checkbox-margin-left** - Checkbox margin left _(default: undefined)_\n- **--ms-checkbox-size** - Checkbox size _(default: undefined)_\n- **--ms-checkbox-scale** - Checkbox scale _(default: undefined)_\n- **--ms-checkbox-align** - Checkbox alignment _(default: undefined)_\n- **--ms-checkbox-bg** - Checkbox background _(default: undefined)_\n- **--ms-checkbox-border** - Checkbox border _(default: undefined)_\n- **--ms-checkbox-border-radius** - Checkbox border radius _(default: undefined)_\n- **--ms-checkbox-checked-bg** - Checked checkbox background _(default: undefined)_\n- **--ms-checkbox-checked-border** - Checked checkbox border _(default: undefined)_\n- **--ms-checkbox-checkmark-color** - Checkmark color _(default: undefined)_\n- **--ms-checkbox-hover-border-color** - Checkbox hover border _(default: undefined)_\n- **--ms-checkbox-disabled-bg** - Disabled checkbox background _(default: undefined)_\n- **--ms-checkbox-disabled-border** - Disabled checkbox border _(default: undefined)_\n- **--ms-checkbox-checked-bg-hover** - Checked checkbox hover background _(default: undefined)_\n- **--ms-checkbox-checked-border-color-hover** - Checked checkbox hover border _(default: undefined)_\n- **--ms-state-min-height** - Shared min-height for the empty and loading states so the dropdown doesn't resize when swapping between them _(default: undefined)_\n- **--ms-empty-padding** - Empty state padding _(default: undefined)_\n- **--ms-empty-font-size** - Empty state font size _(default: undefined)_\n- **--ms-empty-color** - Empty state text color _(default: undefined)_\n- **--ms-loader-padding** - Loader padding _(default: undefined)_\n- **--ms-loader-gap** - Loader gap _(default: undefined)_\n- **--ms-loading-text-font-size** - Loading text font size _(default: undefined)_\n- **--ms-loading-text-color** - Loading text color _(default: undefined)_\n- **--ms-loading-color** - Loading color (semantic) _(default: undefined)_\n- **--ms-badges-gap** - Badges container gap _(default: undefined)_\n- **--ms-badges-margin-bottom** - Badges margin bottom _(default: undefined)_\n- **--ms-badges-margin-top** - Badges margin top _(default: undefined)_\n- **--ms-badges-margin-left** - Badges margin left _(default: undefined)_\n- **--ms-badges-margin-right** - Badges margin right _(default: undefined)_\n- **--ms-badge-gap** - Badge internal gap _(default: undefined)_\n- **--ms-badge-height** - Badge height _(default: undefined)_\n- **--ms-badge-font-size** - Badge font size _(default: undefined)_\n- **--ms-badge-font-weight** - Badge font weight _(default: undefined)_\n- **--ms-badge-border-radius** - Badge border radius _(default: undefined)_\n- **--ms-badge-bg** - Badge background _(default: undefined)_\n- **--ms-badge-bg-hover** - Badge hover background _(default: undefined)_\n- **--ms-badge-bg-active** - Badge active background _(default: undefined)_\n- **--ms-badge-text-padding** - Badge text padding _(default: undefined)_\n- **--ms-badge-text-bg** - Badge text background _(default: undefined)_\n- **--ms-badge-text-color** - Badge text color _(default: undefined)_\n- **--ms-badge-text-border** - Badge text border _(default: undefined)_\n- **--ms-badge-text-bg-hover** - Badge text hover background _(default: undefined)_\n- **--ms-badge-text-color-hover** - Badge text hover color _(default: undefined)_\n- **--ms-badge-remove-width** - Badge remove button width _(default: undefined)_\n- **--ms-badge-remove-bg** - Badge remove button background _(default: undefined)_\n- **--ms-badge-remove-color** - Badge remove button color _(default: undefined)_\n- **--ms-badge-remove-border** - Badge remove button border _(default: undefined)_\n- **--ms-badge-remove-font-size** - Badge remove button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-badge-remove-icon-size** - Badge remove X icon size (mask SVG) _(default: undefined)_\n- **--ms-badge-remove-bg-hover** - Badge remove button hover background _(default: undefined)_\n- **--ms-badge-remove-box-shadow-focus** - Badge remove button focus shadow _(default: undefined)_\n- **--ms-icon-remove** - Remove icon as CSS url() to a mask-friendly SVG; color comes from currentColor _(default: undefined)_\n- **--ms-icon-filter** - Funnel glyph (fullscreen search-mode toggle); chains to --base-icon-filter _(default: undefined)_\n- **--ms-icon-check** - Checkmark glyph (mask) for a checked checkbox/option; chains to --base-icon-check _(default: undefined)_\n- **--ms-icon-indeterminate** - Dash glyph (mask) for a tri-state/partial checkbox; chains to --base-icon-indeterminate _(default: undefined)_\n- **--ms-badge-counter-bg** - Counter badge background _(default: undefined)_\n- **--ms-badge-counter-border** - Counter badge border _(default: undefined)_\n- **--ms-badge-counter-border-color** - Counter badge border color _(default: undefined)_\n- **--ms-badge-counter-border-radius** - Counter badge border radius _(default: undefined)_\n- **--ms-badge-counter-text-color** - Counter badge text color _(default: undefined)_\n- **--ms-badge-counter-text-bg** - Counter badge text background _(default: undefined)_\n- **--ms-badge-counter-remove-bg** - Counter badge remove background _(default: undefined)_\n- **--ms-badge-counter-remove-color** - Counter badge remove color _(default: undefined)_\n- **--ms-badge-counter-remove-bg-hover** - Counter badge remove hover background _(default: undefined)_\n- **--ms-more-badge-bg** - More badge background _(default: undefined)_\n- **--ms-more-badge-hover-bg** - More badge hover background _(default: undefined)_\n- **--ms-more-badge-active-bg** - More badge active background _(default: undefined)_\n- **--ms-count-display-margin-bottom** - Count display margin bottom _(default: undefined)_\n- **--ms-count-display-margin-top** - Count display margin top _(default: undefined)_\n- **--ms-count-display-margin-left** - Count display margin left _(default: undefined)_\n- **--ms-count-display-margin-right** - Count display margin right _(default: undefined)_\n- **--ms-counter-wrapper-bg** - Counter wrapper background _(default: undefined)_\n- **--ms-counter-wrapper-border** - Counter wrapper border _(default: undefined)_\n- **--ms-counter-wrapper-border-radius** - Counter wrapper border radius _(default: undefined)_\n- **--ms-counter-wrapper-padding** - Counter wrapper padding _(default: undefined)_\n- **--ms-counter-wrapper-gap** - Counter wrapper gap _(default: undefined)_\n- **--ms-counter-wrapper-bg-hover** - Counter wrapper hover background _(default: undefined)_\n- **--ms-counter-wrapper-border-color** - Counter wrapper border color _(default: undefined)_\n- **--ms-counter-wrapper-border-color-hover** - Counter wrapper hover border _(default: undefined)_\n- **--ms-count-text-bg** - Count text background _(default: undefined)_\n- **--ms-count-text-border** - Count text border _(default: undefined)_\n- **--ms-count-text-font-size** - Count text font size _(default: undefined)_\n- **--ms-count-text-color** - Count text color _(default: undefined)_\n- **--ms-count-clear-size** - Count clear button size _(default: undefined)_\n- **--ms-count-clear-bg** - Count clear button background _(default: undefined)_\n- **--ms-count-clear-color** - Count clear button color _(default: undefined)_\n- **--ms-count-clear-font-size** - Count clear button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-count-clear-icon-size** - Count clear X icon size (mask SVG) _(default: undefined)_\n- **--ms-count-clear-border-radius** - Count clear button border radius _(default: undefined)_\n- **--ms-count-clear-bg-hover** - Count clear button hover background _(default: undefined)_\n- **--ms-count-clear-color-hover** - Count clear button hover color _(default: undefined)_\n- **--ms-icon-clear** - Clear icon as CSS url() to a mask-friendly SVG; defaults to var(--ms-icon-remove) _(default: undefined)_\n- **--ms-tooltip-bg** - Tooltip background _(default: undefined)_\n- **--ms-tooltip-text-color** - Tooltip text color _(default: undefined)_\n- **--ms-tooltip-color** - Tooltip color _(default: undefined)_\n- **--ms-tooltip-padding** - Tooltip padding _(default: undefined)_\n- **--ms-tooltip-border-radius** - Tooltip border radius _(default: undefined)_\n- **--ms-tooltip-font-size** - Tooltip font size _(default: undefined)_\n- **--ms-tooltip-max-width** - Tooltip max width _(default: undefined)_\n- **--ms-tooltip-shadow** - Tooltip shadow _(default: undefined)_\n- **--ms-tooltip-z-index** - Tooltip z-index _(default: undefined)_\n- **--ms-z-index-popover** - Popover z-index _(default: undefined)_\n- **--ms-selected-popover-width** - Selected popover width _(default: undefined)_\n- **--ms-selected-popover-max-height** - Selected popover max height _(default: undefined)_\n- **--ms-selected-popover-border** - Selected popover border _(default: undefined)_\n- **--ms-selected-popover-border-radius** - Selected popover border radius _(default: undefined)_\n- **--ms-selected-popover-box-shadow** - Selected popover shadow _(default: undefined)_\n- **--ms-selected-popover-bg** - Selected popover background _(default: undefined)_\n- **--ms-selected-popover-border-color** - Selected popover border color _(default: undefined)_\n- **--ms-selected-popover-header-padding** - Popover header padding _(default: undefined)_\n- **--ms-selected-popover-header-bg** - Popover header background _(default: undefined)_\n- **--ms-selected-popover-header-border-bottom** - Popover header border _(default: undefined)_\n- **--ms-selected-popover-header-font-size** - Popover header font size _(default: undefined)_\n- **--ms-selected-popover-header-font-weight** - Popover header font weight _(default: undefined)_\n- **--ms-selected-popover-header-color** - Popover header color _(default: undefined)_\n- **--ms-selected-popover-header-border-color** - Popover header border color _(default: undefined)_\n- **--ms-popover-close-size** - Popover close button size _(default: undefined)_\n- **--ms-selected-popover-close-bg** - Popover close button background _(default: undefined)_\n- **--ms-selected-popover-close-color** - Popover close button color _(default: undefined)_\n- **--ms-selected-popover-close-font-size** - Popover close button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-selected-popover-close-icon-size** - Popover close X icon size (mask SVG) _(default: undefined)_\n- **--ms-selected-popover-close-border-radius** - Popover close button border radius _(default: undefined)_\n- **--ms-selected-popover-close-bg-hover** - Popover close button hover background _(default: undefined)_\n- **--ms-selected-popover-close-color-hover** - Popover close button hover color _(default: undefined)_\n- **--ms-selected-popover-body-gap** - Popover body gap _(default: undefined)_\n- **--ms-selected-popover-body-padding** - Popover body padding _(default: undefined)_\n- **--ms-selected-popover-body-max-height** - Popover body max height _(default: undefined)_\n- **--ms-font-size-2xs** - Extra extra small font size _(default: undefined)_\n- **--ms-font-size-xs** - Extra small font size _(default: undefined)_\n- **--ms-font-size-sm** - Small font size _(default: undefined)_\n- **--ms-font-size-base** - Base font size _(default: undefined)_\n- **--ms-font-size-lg** - Large font size _(default: undefined)_\n- **--ms-font-weight-normal** - Normal font weight _(default: undefined)_\n- **--ms-font-weight-medium** - Medium font weight _(default: undefined)_\n- **--ms-font-weight-semibold** - Semibold font weight _(default: undefined)_\n- **--ms-line-height-none** - No line height (1) _(default: undefined)_\n- **--ms-line-height-tight** - Tight line height _(default: undefined)_\n- **--ms-line-height-normal** - Normal line height _(default: undefined)_\n- **--ms-line-height-relaxed** - Relaxed line height _(default: undefined)_\n- **--ms-border-radius-sm** - Small border radius _(default: undefined)_\n- **--ms-border-radius-md** - Medium border radius _(default: undefined)_\n- **--ms-border-radius-lg** - Large border radius _(default: undefined)_\n- **--ms-border-radius** - Default border radius _(default: undefined)_\n- **--ms-spacing-xs** - Extra small spacing _(default: undefined)_\n- **--ms-spacing-sm** - Small spacing _(default: undefined)_\n- **--ms-spacing-md** - Medium spacing _(default: undefined)_\n- **--ms-spacing-lg** - Large spacing _(default: undefined)_\n- **--ms-transition-fast** - Fast transition duration _(default: undefined)_\n- **--ms-transition-normal** - Normal transition duration _(default: undefined)_\n- **--ms-easing-snappy** - Snappy easing function _(default: undefined)_\n- **--ms-placeholder-opacity** - Placeholder opacity _(default: undefined)_\n- **--ms-disabled-input-opacity** - Disabled input opacity _(default: undefined)_\n- **--ms-scrollbar-width** - Scrollbar width _(default: undefined)_\n- **--ms-scrollbar-track-bg** - Scrollbar track background _(default: undefined)_\n- **--ms-scrollbar-thumb-bg** - Scrollbar thumb background _(default: undefined)_\n- **--ms-scrollbar-thumb-bg-hover** - Scrollbar thumb hover background _(default: undefined)_\n- **--ms-scrollbar-thumb-border-radius** - Scrollbar thumb border radius _(default: undefined)_\n- **--ms-debug-bg** - Debug panel background _(default: undefined)_\n- **--ms-debug-border-color** - Debug panel border _(default: undefined)_\n- **--ms-debug-text-color** - Debug panel text _(default: undefined)_\n- **--ms-debug-border-radius** - Debug panel corner radius _(default: undefined)_\n- **--ms-debug-summary-color** - Debug section heading color _(default: undefined)_\n- **--ms-debug-summary-bg-hover** - Debug section heading hover background _(default: undefined)_\n- **--ms-debug-summary-outline-color** - Debug section heading focus outline _(default: undefined)_\n- **--ms-debug-summary-border-radius** - Debug section heading corner radius _(default: undefined)_\n- **--ms-debug-stats-bg** - Debug stats nested panel background _(default: undefined)_\n- **--ms-debug-stats-border-radius** - Debug stats nested panel corner radius _(default: undefined)_\n- **--ms-debug-bullet-color** - Debug stat bullet marker color _(default: undefined)_\n- **--ms-transform-rotate-180** - 180 degree rotation _(default: undefined)_\n- **--ms-transform-scale-hover** - Hover scale transform _(default: undefined)_\n- **--ms-transform-scale-active** - Active scale transform _(default: undefined)_\n- **--ms-order-first** - Order first (-1) _(default: undefined)_",
+      "description": "\n---\n\n\n### **Events:**\n - **select** - An option was selected. `detail.option` is the selected option; `detail.selectedOptions`/`detail.selectedValues` are the full selection.\n- **deselect** - An option was removed from the selection. `detail.option` is that option.\n- **change** - The selection changed. `detail.selectedOptions`/`detail.selectedValues` are the full selection.\n- **add** - The user chose to create a new option from the typed text (via the \"add new\" prompt or Enter) — requires `allow-add-new`. `detail.value` is the typed text; `detail.option` is the created item when `addNewCallback` produced one.\n- **ready** - The picker was built and painted for the first time (once per element lifetime). Fires right after the first build — synchronously during upgrade for a normal element, or when the render gate is released (`el.ready()` / removing `defer`) for a deferred one. No detail.\n\n### **Methods:**\n - **formResetCallback(): _void_** - Called by the browser when the surrounding <form> is reset. Clears the\r\npicker's selection so the control participates in the standard reset.\n\n\n\n\n\n\n\n- **showMessage(content: _string | HTMLElement_, opts: _MessageOptions_): _void_** - Surface a transient message (\"toast\") on top of the component — visible even in the\r\nfullscreen overlay, where page-level UI is hidden behind the sheet. Content is text or\r\nan element; `opts.variant` sets the tone and `opts.duration` the auto-dismiss (0 =\r\nsticky). Also reached automatically when a `beforeSelect`/`beforeDeselect` callback\r\nreturns a reason string.\n- **hideMessage(): _void_** - Dismiss the transient message shown by showMessage, if any.\n- **clearSearch(): _void_** - Clear the search box and restore the full option list (does not touch the selection — use\r\nclearAll for that). Pair with scrollToValue to reveal then scroll to an option\r\na search had filtered out: `el.clearSearch(); el.scrollToValue(v)`.\n- **search(term: _string_): _void_** - Programmatically set the search text and filter, as if the user typed it (runs\r\n`beforeSearchCallback` / `minSearchLength` / async `searchCallback`). Does not open the dropdown\r\n— call open if you want it visible. Pass `''` to clear (same as clearSearch).\n- **scrollToIndex(index: _number_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll the open dropdown to the option at `index` (into the current filtered list). Returns\r\nfalse if closed or out of range. Deferred internally so `el.open(); el.scrollToIndex(i)` works.\n- **scrollToValue(value: _string | number_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll the open dropdown to the option with this `value`. Returns false if it isn't in the\r\ncurrently visible list (filtered out by search, or under a collapsed tree branch) — call\r\nclearSearch / expand first.\n- **scrollToGroup(name: _string_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll to a group: its header in standard rendering, or the group's first option in\r\nvirtual-scroll mode (no headers there). Returns false in tree mode or if the group is empty\r\nin the current filtered list.\n- **open(): _void_** - Open the dropdown.\n- **close(): _void_** - Close the dropdown.\n- **toggle(): _void_** - Toggle the dropdown open/closed.\n- **ready(): _void_** - Release the `defer` render gate: build the picker now (once), with every\r\noption, callback and listener wired while deferred already in place. No-op\r\nwhen the element wasn't deferred or is already built. `flush()` first so a\r\nsynchronous `el.options = …; el.customStylesCallback = …; el.ready()` lands\r\nthose pending writes in the single build rather than after it. Latched — the\r\ngate never re-closes. Fires the `ready` event on the first build.\n\n### **CSS Properties:**\n - **--ms-rem** - Base sizing unit for proportional scaling (default: 10px) _(default: undefined)_\n- **--ms-accent-color** - Primary accent color _(default: undefined)_\n- **--ms-accent-color-hover** - Accent color on hover _(default: undefined)_\n- **--ms-accent-color-active** - Accent color when pressed _(default: undefined)_\n- **--ms-accent-color-light** - Light accent background _(default: undefined)_\n- **--ms-accent-color-light-hover** - Light accent hover _(default: undefined)_\n- **--ms-text-color-1** - Primary text color _(default: undefined)_\n- **--ms-text-color-2** - Secondary text color _(default: undefined)_\n- **--ms-text-color-3** - Tertiary text color _(default: undefined)_\n- **--ms-text-color-4** - Quaternary text color _(default: undefined)_\n- **--ms-text-color-on-accent** - Text on accent backgrounds _(default: undefined)_\n- **--ms-text-primary** - Legacy alias for text-color-1 _(default: undefined)_\n- **--ms-text-secondary** - Legacy alias for text-color-3 _(default: undefined)_\n- **--ms-primary-bg** - Hover/focus background (options, action buttons, counter); reads --base-hover-bg _(default: undefined)_\n- **--ms-primary-bg-hover** - Active/stronger background (counter badge text); reads --base-active-bg _(default: undefined)_\n- **--ms-border-color** - Default border color _(default: undefined)_\n- **--ms-border** - Full border shorthand _(default: undefined)_\n- **--ms-input-bg** - Input field background _(default: undefined)_\n- **--ms-input-color** - Input text color _(default: undefined)_\n- **--ms-input-border** - Input border _(default: undefined)_\n- **--ms-input-border-hover** - Input border on hover _(default: undefined)_\n- **--ms-input-border-focus** - Input border when focused _(default: undefined)_\n- **--ms-input-placeholder-color** - Placeholder text color _(default: undefined)_\n- **--ms-input-bg-disabled** - Disabled input background _(default: undefined)_\n- **--ms-input-height** - Input height _(default: undefined)_\n- **--ms-input-font-size** - Input font size _(default: undefined)_\n- **--ms-input-border-width** - Input border width _(default: undefined)_\n- **--ms-input-border-radius** - Input border radius _(default: undefined)_\n- **--ms-input-text** - Input text color _(default: undefined)_\n- **--ms-toggle-color** - Toggle icon color _(default: undefined)_\n- **--ms-toggle-icon-color** - Toggle icon color (semantic) _(default: undefined)_\n- **--ms-toggle-icon-color-open** - Toggle icon color when open _(default: undefined)_\n- **--ms-counter-padding** - Counter badge padding _(default: undefined)_\n- **--ms-counter-bg** - Counter badge background _(default: undefined)_\n- **--ms-counter-color** - Counter badge text color _(default: undefined)_\n- **--ms-counter-font-size** - Counter badge font size _(default: undefined)_\n- **--ms-counter-font-weight** - Counter badge font weight _(default: undefined)_\n- **--ms-counter-border-radius** - Counter badge border radius _(default: undefined)_\n- **--ms-counter-bg-hover** - Counter badge hover background _(default: undefined)_\n- **--ms-counter-badge-bg** - Counter badge semantic background _(default: undefined)_\n- **--ms-counter-badge-bg-hover** - Counter badge semantic hover _(default: undefined)_\n- **--ms-counter-badge-color** - Counter badge semantic color _(default: undefined)_\n- **--ms-hint-padding** - Floating hint padding _(default: undefined)_\n- **--ms-hint-border** - Floating hint border _(default: undefined)_\n- **--ms-hint-border-radius** - Floating hint border radius _(default: undefined)_\n- **--ms-hint-box-shadow** - Floating hint shadow _(default: undefined)_\n- **--ms-hint-font-size** - Floating hint font size _(default: undefined)_\n- **--ms-hint-bg** - Floating hint background _(default: undefined)_\n- **--ms-hint-color** - Floating hint text color _(default: undefined)_\n- **--ms-hint-border-color** - Floating hint border color _(default: undefined)_\n- **--ms-dropdown-bg** - Dropdown background _(default: undefined)_\n- **--ms-dropdown-text-color** - Dropdown text color _(default: undefined)_\n- **--ms-dropdown-border** - Dropdown border _(default: undefined)_\n- **--ms-dropdown-border-color** - Dropdown border color _(default: undefined)_\n- **--ms-dropdown-border-radius** - Dropdown border radius _(default: undefined)_\n- **--ms-dropdown-box-shadow** - Dropdown shadow _(default: undefined)_\n- **--ms-dropdown-box-shadow-semantic** - Dropdown semantic shadow _(default: undefined)_\n- **--ms-dropdown-width** - Options dropdown width (defaults to the input width; also set via the dropdown-width attribute) _(default: undefined)_\n- **--ms-options-max-height** - Options list max height _(default: undefined)_\n- **--ms-z-index-dropdown** - Dropdown z-index _(default: undefined)_\n- **--ms-z-index-sticky** - Sticky elements z-index _(default: undefined)_\n- **--ms-actions-gap** - Actions row gap _(default: undefined)_\n- **--ms-actions-padding** - Actions row padding _(default: undefined)_\n- **--ms-actions-border-bottom** - Actions row border _(default: undefined)_\n- **--ms-actions-bg** - Actions row background _(default: undefined)_\n- **--ms-actions-border-color** - Actions row border color _(default: undefined)_\n- **--ms-action-btn-padding** - Action button padding _(default: undefined)_\n- **--ms-action-btn-font-size** - Action button font size _(default: undefined)_\n- **--ms-action-btn-border** - Action button border _(default: undefined)_\n- **--ms-action-btn-border-radius** - Action button border radius _(default: undefined)_\n- **--ms-action-btn-bg** - Action button background _(default: undefined)_\n- **--ms-action-btn-color** - Action button color _(default: undefined)_\n- **--ms-action-btn-bg-hover** - Action button hover background _(default: undefined)_\n- **--ms-action-btn-border-color-hover** - Action button hover border _(default: undefined)_\n- **--ms-action-button-bg** - Semantic action button background _(default: undefined)_\n- **--ms-action-button-bg-hover** - Semantic action button hover _(default: undefined)_\n- **--ms-action-button-border-color** - Semantic action button border _(default: undefined)_\n- **--ms-action-button-border-color-hover** - Semantic action button hover border _(default: undefined)_\n- **--ms-action-button-color** - Semantic action button color _(default: undefined)_\n- **--ms-options-padding** - Options container padding _(default: undefined)_\n- **--ms-group-border-top** - Group border top _(default: undefined)_\n- **--ms-group-margin-top** - Group margin top _(default: undefined)_\n- **--ms-group-padding-top** - Group padding top _(default: undefined)_\n- **--ms-group-border-color** - Group border color _(default: undefined)_\n- **--ms-group-label-padding** - Group label padding _(default: undefined)_\n- **--ms-group-label-font-size** - Group label font size _(default: undefined)_\n- **--ms-group-label-font-weight** - Group label font weight _(default: undefined)_\n- **--ms-group-label-color** - Group label color _(default: undefined)_\n- **--ms-group-label-transform** - Group label text transform _(default: undefined)_\n- **--ms-group-label-letter-spacing** - Group label letter spacing _(default: undefined)_\n- **--ms-option-gap** - Option content gap _(default: undefined)_\n- **--ms-option-padding** - Option padding _(default: undefined)_\n- **--ms-option-padding-h** - Option horizontal padding _(default: undefined)_\n- **--ms-option-color** - Option text color _(default: undefined)_\n- **--ms-option-bg** - Option background _(default: undefined)_\n- **--ms-option-bg-hover** - Option hover background _(default: undefined)_\n- **--ms-option-bg-focused** - Option focused background _(default: undefined)_\n- **--ms-option-outline-focused** - Option focus outline _(default: undefined)_\n- **--ms-option-focus-outline-offset** - Option focus outline offset _(default: undefined)_\n- **--ms-option-bg-matched** - Matched option background _(default: undefined)_\n- **--ms-option-border-matched** - Matched option border _(default: undefined)_\n- **--ms-option-bg-selected** - Selected option background _(default: undefined)_\n- **--ms-option-text-color** - Option text color (semantic) _(default: undefined)_\n- **--ms-option-color-hover** - Option hover color _(default: undefined)_\n- **--ms-option-color-focused** - Option focused color _(default: undefined)_\n- **--ms-option-outline-color-focused** - Option focus outline color _(default: undefined)_\n- **--ms-option-color-matched** - Matched option color _(default: undefined)_\n- **--ms-option-border-matched-color** - Matched option border color _(default: undefined)_\n- **--ms-option-bg-focused-hover** - Focused option hover background _(default: undefined)_\n- **--ms-option-bg-matched-hover** - Matched option hover background _(default: undefined)_\n- **--ms-option-bg-selected-focused** - Selected focused background _(default: undefined)_\n- **--ms-option-bg-selected-matched** - Selected matched background _(default: undefined)_\n- **--ms-option-disabled-bg** - Disabled option background _(default: undefined)_\n- **--ms-option-bg-disabled-selected** - Disabled selected background _(default: undefined)_\n- **--ms-disabled-opacity** - Disabled option opacity _(default: undefined)_\n- **--ms-option-content-gap** - Option content gap _(default: undefined)_\n- **--ms-option-icon-size** - Option icon size _(default: undefined)_\n- **--ms-option-icon-font-size** - Option icon font size _(default: undefined)_\n- **--ms-option-title-font-size** - Option title font size _(default: undefined)_\n- **--ms-option-title-color** - Option title color _(default: undefined)_\n- **--ms-option-subtitle-margin-top** - Option subtitle margin _(default: undefined)_\n- **--ms-option-subtitle-font-size** - Option subtitle font size _(default: undefined)_\n- **--ms-option-subtitle-line-height** - Option subtitle line height _(default: undefined)_\n- **--ms-option-subtitle-color** - Option subtitle color _(default: undefined)_\n- **--ms-option-mark-bg** - Search match highlight background _(default: undefined)_\n- **--ms-option-mark-color** - Search match highlight color _(default: undefined)_\n- **--ms-option-mark-font-weight** - Search match highlight weight _(default: undefined)_\n- **--ms-checkbox-margin-top** - Checkbox margin top _(default: undefined)_\n- **--ms-checkbox-margin-right** - Checkbox margin right _(default: undefined)_\n- **--ms-checkbox-margin-bottom** - Checkbox margin bottom _(default: undefined)_\n- **--ms-checkbox-margin-left** - Checkbox margin left _(default: undefined)_\n- **--ms-checkbox-size** - Checkbox size _(default: undefined)_\n- **--ms-checkbox-scale** - Checkbox scale _(default: undefined)_\n- **--ms-checkbox-align** - Checkbox alignment _(default: undefined)_\n- **--ms-checkbox-bg** - Checkbox background _(default: undefined)_\n- **--ms-checkbox-border** - Checkbox border _(default: undefined)_\n- **--ms-checkbox-border-radius** - Checkbox border radius _(default: undefined)_\n- **--ms-checkbox-checked-bg** - Checked checkbox background _(default: undefined)_\n- **--ms-checkbox-checked-border** - Checked checkbox border _(default: undefined)_\n- **--ms-checkbox-checkmark-color** - Checkmark color _(default: undefined)_\n- **--ms-checkbox-hover-border-color** - Checkbox hover border _(default: undefined)_\n- **--ms-checkbox-disabled-bg** - Disabled checkbox background _(default: undefined)_\n- **--ms-checkbox-disabled-border** - Disabled checkbox border _(default: undefined)_\n- **--ms-checkbox-checked-bg-hover** - Checked checkbox hover background _(default: undefined)_\n- **--ms-checkbox-checked-border-color-hover** - Checked checkbox hover border _(default: undefined)_\n- **--ms-state-min-height** - Shared min-height for the empty and loading states so the dropdown doesn't resize when swapping between them _(default: undefined)_\n- **--ms-empty-padding** - Empty state padding _(default: undefined)_\n- **--ms-empty-font-size** - Empty state font size _(default: undefined)_\n- **--ms-empty-color** - Empty state text color _(default: undefined)_\n- **--ms-loader-padding** - Loader padding _(default: undefined)_\n- **--ms-loader-gap** - Loader gap _(default: undefined)_\n- **--ms-loading-text-font-size** - Loading text font size _(default: undefined)_\n- **--ms-loading-text-color** - Loading text color _(default: undefined)_\n- **--ms-loading-color** - Loading color (semantic) _(default: undefined)_\n- **--ms-badges-gap** - Badges container gap _(default: undefined)_\n- **--ms-badges-margin-bottom** - Badges margin bottom _(default: undefined)_\n- **--ms-badges-margin-top** - Badges margin top _(default: undefined)_\n- **--ms-badges-margin-left** - Badges margin left _(default: undefined)_\n- **--ms-badges-margin-right** - Badges margin right _(default: undefined)_\n- **--ms-badge-gap** - Badge internal gap _(default: undefined)_\n- **--ms-badge-height** - Badge height _(default: undefined)_\n- **--ms-badge-font-size** - Badge font size _(default: undefined)_\n- **--ms-badge-font-weight** - Badge font weight _(default: undefined)_\n- **--ms-badge-border-radius** - Badge border radius _(default: undefined)_\n- **--ms-badge-bg** - Badge background _(default: undefined)_\n- **--ms-badge-bg-hover** - Badge hover background _(default: undefined)_\n- **--ms-badge-bg-active** - Badge active background _(default: undefined)_\n- **--ms-badge-text-padding** - Badge text padding _(default: undefined)_\n- **--ms-badge-text-bg** - Badge text background _(default: undefined)_\n- **--ms-badge-text-color** - Badge text color _(default: undefined)_\n- **--ms-badge-text-border** - Badge text border _(default: undefined)_\n- **--ms-badge-text-bg-hover** - Badge text hover background _(default: undefined)_\n- **--ms-badge-text-color-hover** - Badge text hover color _(default: undefined)_\n- **--ms-badge-remove-width** - Badge remove button width _(default: undefined)_\n- **--ms-badge-remove-bg** - Badge remove button background _(default: undefined)_\n- **--ms-badge-remove-color** - Badge remove button color _(default: undefined)_\n- **--ms-badge-remove-border** - Badge remove button border _(default: undefined)_\n- **--ms-badge-remove-font-size** - Badge remove button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-badge-remove-icon-size** - Badge remove X icon size (mask SVG) _(default: undefined)_\n- **--ms-badge-remove-bg-hover** - Badge remove button hover background _(default: undefined)_\n- **--ms-badge-remove-box-shadow-focus** - Badge remove button focus shadow _(default: undefined)_\n- **--ms-icon-remove** - Remove icon as CSS url() to a mask-friendly SVG; color comes from currentColor _(default: undefined)_\n- **--ms-icon-filter** - Funnel glyph (fullscreen search-mode toggle); chains to --base-icon-filter _(default: undefined)_\n- **--ms-icon-check** - Checkmark glyph (mask) for a checked checkbox/option; chains to --base-icon-check _(default: undefined)_\n- **--ms-icon-indeterminate** - Dash glyph (mask) for a tri-state/partial checkbox; chains to --base-icon-indeterminate _(default: undefined)_\n- **--ms-icon-check-size** - mask-size for the checkmark/dash glyph inside the checkbox box; chains to --base-icon-check-size (default 68%, the same knob as pure-admin's .pa-checkbox) _(default: undefined)_\n- **--ms-badge-counter-bg** - Counter badge background _(default: undefined)_\n- **--ms-badge-counter-border** - Counter badge border _(default: undefined)_\n- **--ms-badge-counter-border-color** - Counter badge border color _(default: undefined)_\n- **--ms-badge-counter-border-radius** - Counter badge border radius _(default: undefined)_\n- **--ms-badge-counter-text-color** - Counter badge text color _(default: undefined)_\n- **--ms-badge-counter-text-bg** - Counter badge text background _(default: undefined)_\n- **--ms-badge-counter-remove-bg** - Counter badge remove background _(default: undefined)_\n- **--ms-badge-counter-remove-color** - Counter badge remove color _(default: undefined)_\n- **--ms-badge-counter-remove-bg-hover** - Counter badge remove hover background _(default: undefined)_\n- **--ms-more-badge-bg** - More badge background _(default: undefined)_\n- **--ms-more-badge-hover-bg** - More badge hover background _(default: undefined)_\n- **--ms-more-badge-active-bg** - More badge active background _(default: undefined)_\n- **--ms-count-display-margin-bottom** - Count display margin bottom _(default: undefined)_\n- **--ms-count-display-margin-top** - Count display margin top _(default: undefined)_\n- **--ms-count-display-margin-left** - Count display margin left _(default: undefined)_\n- **--ms-count-display-margin-right** - Count display margin right _(default: undefined)_\n- **--ms-counter-wrapper-bg** - Counter wrapper background _(default: undefined)_\n- **--ms-counter-wrapper-border** - Counter wrapper border _(default: undefined)_\n- **--ms-counter-wrapper-border-radius** - Counter wrapper border radius _(default: undefined)_\n- **--ms-counter-wrapper-padding** - Counter wrapper padding _(default: undefined)_\n- **--ms-counter-wrapper-gap** - Counter wrapper gap _(default: undefined)_\n- **--ms-counter-wrapper-bg-hover** - Counter wrapper hover background _(default: undefined)_\n- **--ms-counter-wrapper-border-color** - Counter wrapper border color _(default: undefined)_\n- **--ms-counter-wrapper-border-color-hover** - Counter wrapper hover border _(default: undefined)_\n- **--ms-count-text-bg** - Count text background _(default: undefined)_\n- **--ms-count-text-border** - Count text border _(default: undefined)_\n- **--ms-count-text-font-size** - Count text font size _(default: undefined)_\n- **--ms-count-text-color** - Count text color _(default: undefined)_\n- **--ms-count-clear-size** - Count clear button size _(default: undefined)_\n- **--ms-count-clear-bg** - Count clear button background _(default: undefined)_\n- **--ms-count-clear-color** - Count clear button color _(default: undefined)_\n- **--ms-count-clear-font-size** - Count clear button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-count-clear-icon-size** - Count clear X icon size (mask SVG) _(default: undefined)_\n- **--ms-count-clear-border-radius** - Count clear button border radius _(default: undefined)_\n- **--ms-count-clear-bg-hover** - Count clear button hover background _(default: undefined)_\n- **--ms-count-clear-color-hover** - Count clear button hover color _(default: undefined)_\n- **--ms-icon-clear** - Clear icon as CSS url() to a mask-friendly SVG; defaults to var(--ms-icon-remove) _(default: undefined)_\n- **--ms-tooltip-bg** - Tooltip background _(default: undefined)_\n- **--ms-tooltip-text-color** - Tooltip text color _(default: undefined)_\n- **--ms-tooltip-color** - Tooltip color _(default: undefined)_\n- **--ms-tooltip-padding** - Tooltip padding _(default: undefined)_\n- **--ms-tooltip-border-radius** - Tooltip border radius _(default: undefined)_\n- **--ms-tooltip-font-size** - Tooltip font size _(default: undefined)_\n- **--ms-tooltip-max-width** - Tooltip max width _(default: undefined)_\n- **--ms-tooltip-shadow** - Tooltip shadow _(default: undefined)_\n- **--ms-tooltip-z-index** - Tooltip z-index _(default: undefined)_\n- **--ms-z-index-popover** - Popover z-index _(default: undefined)_\n- **--ms-selected-popover-width** - Selected popover width _(default: undefined)_\n- **--ms-selected-popover-max-height** - Selected popover max height _(default: undefined)_\n- **--ms-selected-popover-border** - Selected popover border _(default: undefined)_\n- **--ms-selected-popover-border-radius** - Selected popover border radius _(default: undefined)_\n- **--ms-selected-popover-box-shadow** - Selected popover shadow _(default: undefined)_\n- **--ms-selected-popover-bg** - Selected popover background _(default: undefined)_\n- **--ms-selected-popover-border-color** - Selected popover border color _(default: undefined)_\n- **--ms-selected-popover-header-padding** - Popover header padding _(default: undefined)_\n- **--ms-selected-popover-header-bg** - Popover header background _(default: undefined)_\n- **--ms-selected-popover-header-border-bottom** - Popover header border _(default: undefined)_\n- **--ms-selected-popover-header-font-size** - Popover header font size _(default: undefined)_\n- **--ms-selected-popover-header-font-weight** - Popover header font weight _(default: undefined)_\n- **--ms-selected-popover-header-color** - Popover header color _(default: undefined)_\n- **--ms-selected-popover-header-border-color** - Popover header border color _(default: undefined)_\n- **--ms-popover-close-size** - Popover close button size _(default: undefined)_\n- **--ms-selected-popover-close-bg** - Popover close button background _(default: undefined)_\n- **--ms-selected-popover-close-color** - Popover close button color _(default: undefined)_\n- **--ms-selected-popover-close-font-size** - Popover close button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-selected-popover-close-icon-size** - Popover close X icon size (mask SVG) _(default: undefined)_\n- **--ms-selected-popover-close-border-radius** - Popover close button border radius _(default: undefined)_\n- **--ms-selected-popover-close-bg-hover** - Popover close button hover background _(default: undefined)_\n- **--ms-selected-popover-close-color-hover** - Popover close button hover color _(default: undefined)_\n- **--ms-selected-popover-body-gap** - Popover body gap _(default: undefined)_\n- **--ms-selected-popover-body-padding** - Popover body padding _(default: undefined)_\n- **--ms-selected-popover-body-max-height** - Popover body max height _(default: undefined)_\n- **--ms-font-size-2xs** - Extra extra small font size _(default: undefined)_\n- **--ms-font-size-xs** - Extra small font size _(default: undefined)_\n- **--ms-font-size-sm** - Small font size _(default: undefined)_\n- **--ms-font-size-base** - Base font size _(default: undefined)_\n- **--ms-font-size-lg** - Large font size _(default: undefined)_\n- **--ms-font-weight-normal** - Normal font weight _(default: undefined)_\n- **--ms-font-weight-medium** - Medium font weight _(default: undefined)_\n- **--ms-font-weight-semibold** - Semibold font weight _(default: undefined)_\n- **--ms-line-height-none** - No line height (1) _(default: undefined)_\n- **--ms-line-height-tight** - Tight line height _(default: undefined)_\n- **--ms-line-height-normal** - Normal line height _(default: undefined)_\n- **--ms-line-height-relaxed** - Relaxed line height _(default: undefined)_\n- **--ms-border-radius-sm** - Small border radius _(default: undefined)_\n- **--ms-border-radius-md** - Medium border radius _(default: undefined)_\n- **--ms-border-radius-lg** - Large border radius _(default: undefined)_\n- **--ms-border-radius** - Default border radius _(default: undefined)_\n- **--ms-spacing-xs** - Extra small spacing _(default: undefined)_\n- **--ms-spacing-sm** - Small spacing _(default: undefined)_\n- **--ms-spacing-md** - Medium spacing _(default: undefined)_\n- **--ms-spacing-lg** - Large spacing _(default: undefined)_\n- **--ms-transition-fast** - Fast transition duration _(default: undefined)_\n- **--ms-transition-normal** - Normal transition duration _(default: undefined)_\n- **--ms-easing-snappy** - Snappy easing function _(default: undefined)_\n- **--ms-placeholder-opacity** - Placeholder opacity _(default: undefined)_\n- **--ms-disabled-input-opacity** - Disabled input opacity _(default: undefined)_\n- **--ms-scrollbar-width** - Scrollbar width _(default: undefined)_\n- **--ms-scrollbar-track-bg** - Scrollbar track background _(default: undefined)_\n- **--ms-scrollbar-thumb-bg** - Scrollbar thumb background _(default: undefined)_\n- **--ms-scrollbar-thumb-bg-hover** - Scrollbar thumb hover background _(default: undefined)_\n- **--ms-scrollbar-thumb-border-radius** - Scrollbar thumb border radius _(default: undefined)_\n- **--ms-debug-bg** - Debug panel background _(default: undefined)_\n- **--ms-debug-border-color** - Debug panel border _(default: undefined)_\n- **--ms-debug-text-color** - Debug panel text _(default: undefined)_\n- **--ms-debug-border-radius** - Debug panel corner radius _(default: undefined)_\n- **--ms-debug-summary-color** - Debug section heading color _(default: undefined)_\n- **--ms-debug-summary-bg-hover** - Debug section heading hover background _(default: undefined)_\n- **--ms-debug-summary-outline-color** - Debug section heading focus outline _(default: undefined)_\n- **--ms-debug-summary-border-radius** - Debug section heading corner radius _(default: undefined)_\n- **--ms-debug-stats-bg** - Debug stats nested panel background _(default: undefined)_\n- **--ms-debug-stats-border-radius** - Debug stats nested panel corner radius _(default: undefined)_\n- **--ms-debug-bullet-color** - Debug stat bullet marker color _(default: undefined)_\n- **--ms-transform-rotate-180** - 180 degree rotation _(default: undefined)_\n- **--ms-transform-scale-hover** - Hover scale transform _(default: undefined)_\n- **--ms-transform-scale-active** - Active scale transform _(default: undefined)_\n- **--ms-order-first** - Order first (-1) _(default: undefined)_",
       "attributes": [
         {
           "name": "search-hint",
@@ -153,7 +153,7 @@
         },
         {
           "name": "checkbox-mode",
-          "description": "Tree checkbox interaction.\n- `independent` (default) — toggles only the clicked node.\n- `cascade` — checks a node whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches.\n\nTree + multiple only.",
+          "description": "Tree checkbox interaction.\n- `cascade` (default) — checks a node's whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches. This is what most tree-select UIs do, so it's the default.\n- `independent` — toggles only the clicked node, ignoring ancestors/descendants.\n\nTree + multiple only — has no effect on flat lists or single-select (there is no subtree to cascade into).",
           "values": [{ "name": "independent" }, { "name": "cascade" }]
         },
         {
@@ -165,6 +165,11 @@
             { "name": "all" }
           ]
         },
+        {
+          "name": "group-select-mode",
+          "description": "Group-header selection in a FLAT (non-tree) grouped, multi-select list.\n- `none` (default) — group headers are inert labels.\n- `cascade` — each header shows a tristate checkbox that checks/unchecks all of that group's currently-visible members; a partially-selected group reads indeterminate. The group itself is never a selected value (getValue / badges / form carry member values only).\n\nFlat + multiple only — no effect in tree mode (use `checkbox-mode`) or single-select.",
+          "values": [{ "name": "none" }, { "name": "cascade" }]
+        },
         {
           "name": "badges-display-mode",
           "description": "How the current selection is shown in the control.",
@@ -191,6 +196,22 @@
           "description": "How `badgesThreshold` is interpreted: collapse to a count badge, or keep partial badges + a \"more\" badge.",
           "values": [{ "name": "count" }, { "name": "partial" }]
         },
+        {
+          "name": "selected-order",
+          "description": "Order of the CURRENTLY-SELECTED items where they are displayed — badges, partial mode (which items sit behind the \"+N more\" badge), and the selected-items popover. Display only: `getValue()`, the form output, and `getSelected()` keep as-selected (insertion) order, and the options dropdown is never reordered.\n- `as-selected` (default) — the order items were picked.\n- `label-asc` / `label-desc` — by the badge label, A→Z / Z→A (locale-aware).\n- `member` — by the `selected-order-member` property (or `getSelectedOrderCallback`); numeric keys sort numerically, everything else with a locale string compare.\n- `custom` — delegate to `selectedOrderCompareCallback`.",
+          "values": [
+            { "name": "as-selected" },
+            { "name": "label-asc" },
+            { "name": "label-desc" },
+            { "name": "member" },
+            { "name": "custom" }
+          ]
+        },
+        {
+          "name": "selected-order-member",
+          "description": "Property name used as the sort key when `selected-order=\"member\"`. Sorts the SELECTED-items display only (not the dropdown). Overridden by `getSelectedOrderCallback`.",
+          "values": []
+        },
         {
           "name": "search-input-mode",
           "description": "Search field mode: editable, read-only, or hidden.",
@@ -465,6 +486,11 @@
           "description": "Render an in-component debug panel.",
           "values": []
         },
+        {
+          "name": "defer",
+          "description": "Hold the initial render. When the `defer` attribute is present on upgrade the component builds nothing (it only reserves space) — so options, callbacks (e.g. `customStylesCallback`) and event listeners can all be wired first, then released with `el.ready()` (or by removing the `defer` attribute, for server-driven frameworks). The release builds the picker ONCE with everything already in place, avoiding the upgrade-then-restyle flash. Absent (default): builds immediately on connect. Latched — once released the gate never re-closes.",
+          "values": []
+        },
         {
           "name": "data-options",
           "description": "HTML-authoring source for the option list, parsed per `data-options-format`. Reactive: changing either attribute re-renders. Prefer the `options` property in JS; a set `options` property and declarative <option> children both win over this.",

package/web-types.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@keenmate/web-multiselect",
-  "version": "2.0.1",
+  "version": "2.2.0-rc01",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "web-multiselect",
-          "description": "\n---\n\n\n### **Events:**\n - **select** - An option was selected. `detail.option` is the selected option; `detail.selectedOptions`/`detail.selectedValues` are the full selection.\n- **deselect** - An option was removed from the selection. `detail.option` is that option.\n- **change** - The selection changed. `detail.selectedOptions`/`detail.selectedValues` are the full selection.\n- **add** - The user chose to create a new option from the typed text (via the \"add new\" prompt or Enter) — requires `allow-add-new`. `detail.value` is the typed text; `detail.option` is the created item when `addNewCallback` produced one.\n\n### **Methods:**\n - **formResetCallback(): _void_** - Called by the browser when the surrounding <form> is reset. Clears the\r\npicker's selection so the control participates in the standard reset.\n\n\n\n\n\n\n\n- **showMessage(content: _string | HTMLElement_, opts: _MessageOptions_): _void_** - Surface a transient message (\"toast\") on top of the component — visible even in the\r\nfullscreen overlay, where page-level UI is hidden behind the sheet. Content is text or\r\nan element; `opts.variant` sets the tone and `opts.duration` the auto-dismiss (0 =\r\nsticky). Also reached automatically when a `beforeSelect`/`beforeDeselect` callback\r\nreturns a reason string.\n- **hideMessage(): _void_** - Dismiss the transient message shown by showMessage, if any.\n- **clearSearch(): _void_** - Clear the search box and restore the full option list (does not touch the selection — use\r\nclearAll for that). Pair with scrollToValue to reveal then scroll to an option\r\na search had filtered out: `el.clearSearch(); el.scrollToValue(v)`.\n- **search(term: _string_): _void_** - Programmatically set the search text and filter, as if the user typed it (runs\r\n`beforeSearchCallback` / `minSearchLength` / async `searchCallback`). Does not open the dropdown\r\n— call open if you want it visible. Pass `''` to clear (same as clearSearch).\n- **scrollToIndex(index: _number_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll the open dropdown to the option at `index` (into the current filtered list). Returns\r\nfalse if closed or out of range. Deferred internally so `el.open(); el.scrollToIndex(i)` works.\n- **scrollToValue(value: _string | number_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll the open dropdown to the option with this `value`. Returns false if it isn't in the\r\ncurrently visible list (filtered out by search, or under a collapsed tree branch) — call\r\nclearSearch / expand first.\n- **scrollToGroup(name: _string_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll to a group: its header in standard rendering, or the group's first option in\r\nvirtual-scroll mode (no headers there). Returns false in tree mode or if the group is empty\r\nin the current filtered list.\n- **open(): _void_** - Open the dropdown.\n- **close(): _void_** - Close the dropdown.\n- **toggle(): _void_** - Toggle the dropdown open/closed.\n\n### **CSS Properties:**\n - **--ms-rem** - Base sizing unit for proportional scaling (default: 10px) _(default: undefined)_\n- **--ms-accent-color** - Primary accent color _(default: undefined)_\n- **--ms-accent-color-hover** - Accent color on hover _(default: undefined)_\n- **--ms-accent-color-active** - Accent color when pressed _(default: undefined)_\n- **--ms-accent-color-light** - Light accent background _(default: undefined)_\n- **--ms-accent-color-light-hover** - Light accent hover _(default: undefined)_\n- **--ms-text-color-1** - Primary text color _(default: undefined)_\n- **--ms-text-color-2** - Secondary text color _(default: undefined)_\n- **--ms-text-color-3** - Tertiary text color _(default: undefined)_\n- **--ms-text-color-4** - Quaternary text color _(default: undefined)_\n- **--ms-text-color-on-accent** - Text on accent backgrounds _(default: undefined)_\n- **--ms-text-primary** - Legacy alias for text-color-1 _(default: undefined)_\n- **--ms-text-secondary** - Legacy alias for text-color-3 _(default: undefined)_\n- **--ms-primary-bg** - Hover/focus background (options, action buttons, counter); reads --base-hover-bg _(default: undefined)_\n- **--ms-primary-bg-hover** - Active/stronger background (counter badge text); reads --base-active-bg _(default: undefined)_\n- **--ms-border-color** - Default border color _(default: undefined)_\n- **--ms-border** - Full border shorthand _(default: undefined)_\n- **--ms-input-bg** - Input field background _(default: undefined)_\n- **--ms-input-color** - Input text color _(default: undefined)_\n- **--ms-input-border** - Input border _(default: undefined)_\n- **--ms-input-border-hover** - Input border on hover _(default: undefined)_\n- **--ms-input-border-focus** - Input border when focused _(default: undefined)_\n- **--ms-input-placeholder-color** - Placeholder text color _(default: undefined)_\n- **--ms-input-bg-disabled** - Disabled input background _(default: undefined)_\n- **--ms-input-height** - Input height _(default: undefined)_\n- **--ms-input-font-size** - Input font size _(default: undefined)_\n- **--ms-input-border-width** - Input border width _(default: undefined)_\n- **--ms-input-border-radius** - Input border radius _(default: undefined)_\n- **--ms-input-text** - Input text color _(default: undefined)_\n- **--ms-toggle-color** - Toggle icon color _(default: undefined)_\n- **--ms-toggle-icon-color** - Toggle icon color (semantic) _(default: undefined)_\n- **--ms-toggle-icon-color-open** - Toggle icon color when open _(default: undefined)_\n- **--ms-counter-padding** - Counter badge padding _(default: undefined)_\n- **--ms-counter-bg** - Counter badge background _(default: undefined)_\n- **--ms-counter-color** - Counter badge text color _(default: undefined)_\n- **--ms-counter-font-size** - Counter badge font size _(default: undefined)_\n- **--ms-counter-font-weight** - Counter badge font weight _(default: undefined)_\n- **--ms-counter-border-radius** - Counter badge border radius _(default: undefined)_\n- **--ms-counter-bg-hover** - Counter badge hover background _(default: undefined)_\n- **--ms-counter-badge-bg** - Counter badge semantic background _(default: undefined)_\n- **--ms-counter-badge-bg-hover** - Counter badge semantic hover _(default: undefined)_\n- **--ms-counter-badge-color** - Counter badge semantic color _(default: undefined)_\n- **--ms-hint-padding** - Floating hint padding _(default: undefined)_\n- **--ms-hint-border** - Floating hint border _(default: undefined)_\n- **--ms-hint-border-radius** - Floating hint border radius _(default: undefined)_\n- **--ms-hint-box-shadow** - Floating hint shadow _(default: undefined)_\n- **--ms-hint-font-size** - Floating hint font size _(default: undefined)_\n- **--ms-hint-bg** - Floating hint background _(default: undefined)_\n- **--ms-hint-color** - Floating hint text color _(default: undefined)_\n- **--ms-hint-border-color** - Floating hint border color _(default: undefined)_\n- **--ms-dropdown-bg** - Dropdown background _(default: undefined)_\n- **--ms-dropdown-text-color** - Dropdown text color _(default: undefined)_\n- **--ms-dropdown-border** - Dropdown border _(default: undefined)_\n- **--ms-dropdown-border-color** - Dropdown border color _(default: undefined)_\n- **--ms-dropdown-border-radius** - Dropdown border radius _(default: undefined)_\n- **--ms-dropdown-box-shadow** - Dropdown shadow _(default: undefined)_\n- **--ms-dropdown-box-shadow-semantic** - Dropdown semantic shadow _(default: undefined)_\n- **--ms-dropdown-width** - Options dropdown width (defaults to the input width; also set via the dropdown-width attribute) _(default: undefined)_\n- **--ms-options-max-height** - Options list max height _(default: undefined)_\n- **--ms-z-index-dropdown** - Dropdown z-index _(default: undefined)_\n- **--ms-z-index-sticky** - Sticky elements z-index _(default: undefined)_\n- **--ms-actions-gap** - Actions row gap _(default: undefined)_\n- **--ms-actions-padding** - Actions row padding _(default: undefined)_\n- **--ms-actions-border-bottom** - Actions row border _(default: undefined)_\n- **--ms-actions-bg** - Actions row background _(default: undefined)_\n- **--ms-actions-border-color** - Actions row border color _(default: undefined)_\n- **--ms-action-btn-padding** - Action button padding _(default: undefined)_\n- **--ms-action-btn-font-size** - Action button font size _(default: undefined)_\n- **--ms-action-btn-border** - Action button border _(default: undefined)_\n- **--ms-action-btn-border-radius** - Action button border radius _(default: undefined)_\n- **--ms-action-btn-bg** - Action button background _(default: undefined)_\n- **--ms-action-btn-color** - Action button color _(default: undefined)_\n- **--ms-action-btn-bg-hover** - Action button hover background _(default: undefined)_\n- **--ms-action-btn-border-color-hover** - Action button hover border _(default: undefined)_\n- **--ms-action-button-bg** - Semantic action button background _(default: undefined)_\n- **--ms-action-button-bg-hover** - Semantic action button hover _(default: undefined)_\n- **--ms-action-button-border-color** - Semantic action button border _(default: undefined)_\n- **--ms-action-button-border-color-hover** - Semantic action button hover border _(default: undefined)_\n- **--ms-action-button-color** - Semantic action button color _(default: undefined)_\n- **--ms-options-padding** - Options container padding _(default: undefined)_\n- **--ms-group-border-top** - Group border top _(default: undefined)_\n- **--ms-group-margin-top** - Group margin top _(default: undefined)_\n- **--ms-group-padding-top** - Group padding top _(default: undefined)_\n- **--ms-group-border-color** - Group border color _(default: undefined)_\n- **--ms-group-label-padding** - Group label padding _(default: undefined)_\n- **--ms-group-label-font-size** - Group label font size _(default: undefined)_\n- **--ms-group-label-font-weight** - Group label font weight _(default: undefined)_\n- **--ms-group-label-color** - Group label color _(default: undefined)_\n- **--ms-group-label-transform** - Group label text transform _(default: undefined)_\n- **--ms-group-label-letter-spacing** - Group label letter spacing _(default: undefined)_\n- **--ms-option-gap** - Option content gap _(default: undefined)_\n- **--ms-option-padding** - Option padding _(default: undefined)_\n- **--ms-option-padding-h** - Option horizontal padding _(default: undefined)_\n- **--ms-option-color** - Option text color _(default: undefined)_\n- **--ms-option-bg** - Option background _(default: undefined)_\n- **--ms-option-bg-hover** - Option hover background _(default: undefined)_\n- **--ms-option-bg-focused** - Option focused background _(default: undefined)_\n- **--ms-option-outline-focused** - Option focus outline _(default: undefined)_\n- **--ms-option-focus-outline-offset** - Option focus outline offset _(default: undefined)_\n- **--ms-option-bg-matched** - Matched option background _(default: undefined)_\n- **--ms-option-border-matched** - Matched option border _(default: undefined)_\n- **--ms-option-bg-selected** - Selected option background _(default: undefined)_\n- **--ms-option-text-color** - Option text color (semantic) _(default: undefined)_\n- **--ms-option-color-hover** - Option hover color _(default: undefined)_\n- **--ms-option-color-focused** - Option focused color _(default: undefined)_\n- **--ms-option-outline-color-focused** - Option focus outline color _(default: undefined)_\n- **--ms-option-color-matched** - Matched option color _(default: undefined)_\n- **--ms-option-border-matched-color** - Matched option border color _(default: undefined)_\n- **--ms-option-bg-focused-hover** - Focused option hover background _(default: undefined)_\n- **--ms-option-bg-matched-hover** - Matched option hover background _(default: undefined)_\n- **--ms-option-bg-selected-focused** - Selected focused background _(default: undefined)_\n- **--ms-option-bg-selected-matched** - Selected matched background _(default: undefined)_\n- **--ms-option-disabled-bg** - Disabled option background _(default: undefined)_\n- **--ms-option-bg-disabled-selected** - Disabled selected background _(default: undefined)_\n- **--ms-disabled-opacity** - Disabled option opacity _(default: undefined)_\n- **--ms-option-content-gap** - Option content gap _(default: undefined)_\n- **--ms-option-icon-size** - Option icon size _(default: undefined)_\n- **--ms-option-icon-font-size** - Option icon font size _(default: undefined)_\n- **--ms-option-title-font-size** - Option title font size _(default: undefined)_\n- **--ms-option-title-color** - Option title color _(default: undefined)_\n- **--ms-option-subtitle-margin-top** - Option subtitle margin _(default: undefined)_\n- **--ms-option-subtitle-font-size** - Option subtitle font size _(default: undefined)_\n- **--ms-option-subtitle-line-height** - Option subtitle line height _(default: undefined)_\n- **--ms-option-subtitle-color** - Option subtitle color _(default: undefined)_\n- **--ms-option-mark-bg** - Search match highlight background _(default: undefined)_\n- **--ms-option-mark-color** - Search match highlight color _(default: undefined)_\n- **--ms-option-mark-font-weight** - Search match highlight weight _(default: undefined)_\n- **--ms-checkbox-margin-top** - Checkbox margin top _(default: undefined)_\n- **--ms-checkbox-margin-right** - Checkbox margin right _(default: undefined)_\n- **--ms-checkbox-margin-bottom** - Checkbox margin bottom _(default: undefined)_\n- **--ms-checkbox-margin-left** - Checkbox margin left _(default: undefined)_\n- **--ms-checkbox-size** - Checkbox size _(default: undefined)_\n- **--ms-checkbox-scale** - Checkbox scale _(default: undefined)_\n- **--ms-checkbox-align** - Checkbox alignment _(default: undefined)_\n- **--ms-checkbox-bg** - Checkbox background _(default: undefined)_\n- **--ms-checkbox-border** - Checkbox border _(default: undefined)_\n- **--ms-checkbox-border-radius** - Checkbox border radius _(default: undefined)_\n- **--ms-checkbox-checked-bg** - Checked checkbox background _(default: undefined)_\n- **--ms-checkbox-checked-border** - Checked checkbox border _(default: undefined)_\n- **--ms-checkbox-checkmark-color** - Checkmark color _(default: undefined)_\n- **--ms-checkbox-hover-border-color** - Checkbox hover border _(default: undefined)_\n- **--ms-checkbox-disabled-bg** - Disabled checkbox background _(default: undefined)_\n- **--ms-checkbox-disabled-border** - Disabled checkbox border _(default: undefined)_\n- **--ms-checkbox-checked-bg-hover** - Checked checkbox hover background _(default: undefined)_\n- **--ms-checkbox-checked-border-color-hover** - Checked checkbox hover border _(default: undefined)_\n- **--ms-state-min-height** - Shared min-height for the empty and loading states so the dropdown doesn't resize when swapping between them _(default: undefined)_\n- **--ms-empty-padding** - Empty state padding _(default: undefined)_\n- **--ms-empty-font-size** - Empty state font size _(default: undefined)_\n- **--ms-empty-color** - Empty state text color _(default: undefined)_\n- **--ms-loader-padding** - Loader padding _(default: undefined)_\n- **--ms-loader-gap** - Loader gap _(default: undefined)_\n- **--ms-loading-text-font-size** - Loading text font size _(default: undefined)_\n- **--ms-loading-text-color** - Loading text color _(default: undefined)_\n- **--ms-loading-color** - Loading color (semantic) _(default: undefined)_\n- **--ms-badges-gap** - Badges container gap _(default: undefined)_\n- **--ms-badges-margin-bottom** - Badges margin bottom _(default: undefined)_\n- **--ms-badges-margin-top** - Badges margin top _(default: undefined)_\n- **--ms-badges-margin-left** - Badges margin left _(default: undefined)_\n- **--ms-badges-margin-right** - Badges margin right _(default: undefined)_\n- **--ms-badge-gap** - Badge internal gap _(default: undefined)_\n- **--ms-badge-height** - Badge height _(default: undefined)_\n- **--ms-badge-font-size** - Badge font size _(default: undefined)_\n- **--ms-badge-font-weight** - Badge font weight _(default: undefined)_\n- **--ms-badge-border-radius** - Badge border radius _(default: undefined)_\n- **--ms-badge-bg** - Badge background _(default: undefined)_\n- **--ms-badge-bg-hover** - Badge hover background _(default: undefined)_\n- **--ms-badge-bg-active** - Badge active background _(default: undefined)_\n- **--ms-badge-text-padding** - Badge text padding _(default: undefined)_\n- **--ms-badge-text-bg** - Badge text background _(default: undefined)_\n- **--ms-badge-text-color** - Badge text color _(default: undefined)_\n- **--ms-badge-text-border** - Badge text border _(default: undefined)_\n- **--ms-badge-text-bg-hover** - Badge text hover background _(default: undefined)_\n- **--ms-badge-text-color-hover** - Badge text hover color _(default: undefined)_\n- **--ms-badge-remove-width** - Badge remove button width _(default: undefined)_\n- **--ms-badge-remove-bg** - Badge remove button background _(default: undefined)_\n- **--ms-badge-remove-color** - Badge remove button color _(default: undefined)_\n- **--ms-badge-remove-border** - Badge remove button border _(default: undefined)_\n- **--ms-badge-remove-font-size** - Badge remove button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-badge-remove-icon-size** - Badge remove X icon size (mask SVG) _(default: undefined)_\n- **--ms-badge-remove-bg-hover** - Badge remove button hover background _(default: undefined)_\n- **--ms-badge-remove-box-shadow-focus** - Badge remove button focus shadow _(default: undefined)_\n- **--ms-icon-remove** - Remove icon as CSS url() to a mask-friendly SVG; color comes from currentColor _(default: undefined)_\n- **--ms-icon-filter** - Funnel glyph (fullscreen search-mode toggle); chains to --base-icon-filter _(default: undefined)_\n- **--ms-icon-check** - Checkmark glyph (mask) for a checked checkbox/option; chains to --base-icon-check _(default: undefined)_\n- **--ms-icon-indeterminate** - Dash glyph (mask) for a tri-state/partial checkbox; chains to --base-icon-indeterminate _(default: undefined)_\n- **--ms-badge-counter-bg** - Counter badge background _(default: undefined)_\n- **--ms-badge-counter-border** - Counter badge border _(default: undefined)_\n- **--ms-badge-counter-border-color** - Counter badge border color _(default: undefined)_\n- **--ms-badge-counter-border-radius** - Counter badge border radius _(default: undefined)_\n- **--ms-badge-counter-text-color** - Counter badge text color _(default: undefined)_\n- **--ms-badge-counter-text-bg** - Counter badge text background _(default: undefined)_\n- **--ms-badge-counter-remove-bg** - Counter badge remove background _(default: undefined)_\n- **--ms-badge-counter-remove-color** - Counter badge remove color _(default: undefined)_\n- **--ms-badge-counter-remove-bg-hover** - Counter badge remove hover background _(default: undefined)_\n- **--ms-more-badge-bg** - More badge background _(default: undefined)_\n- **--ms-more-badge-hover-bg** - More badge hover background _(default: undefined)_\n- **--ms-more-badge-active-bg** - More badge active background _(default: undefined)_\n- **--ms-count-display-margin-bottom** - Count display margin bottom _(default: undefined)_\n- **--ms-count-display-margin-top** - Count display margin top _(default: undefined)_\n- **--ms-count-display-margin-left** - Count display margin left _(default: undefined)_\n- **--ms-count-display-margin-right** - Count display margin right _(default: undefined)_\n- **--ms-counter-wrapper-bg** - Counter wrapper background _(default: undefined)_\n- **--ms-counter-wrapper-border** - Counter wrapper border _(default: undefined)_\n- **--ms-counter-wrapper-border-radius** - Counter wrapper border radius _(default: undefined)_\n- **--ms-counter-wrapper-padding** - Counter wrapper padding _(default: undefined)_\n- **--ms-counter-wrapper-gap** - Counter wrapper gap _(default: undefined)_\n- **--ms-counter-wrapper-bg-hover** - Counter wrapper hover background _(default: undefined)_\n- **--ms-counter-wrapper-border-color** - Counter wrapper border color _(default: undefined)_\n- **--ms-counter-wrapper-border-color-hover** - Counter wrapper hover border _(default: undefined)_\n- **--ms-count-text-bg** - Count text background _(default: undefined)_\n- **--ms-count-text-border** - Count text border _(default: undefined)_\n- **--ms-count-text-font-size** - Count text font size _(default: undefined)_\n- **--ms-count-text-color** - Count text color _(default: undefined)_\n- **--ms-count-clear-size** - Count clear button size _(default: undefined)_\n- **--ms-count-clear-bg** - Count clear button background _(default: undefined)_\n- **--ms-count-clear-color** - Count clear button color _(default: undefined)_\n- **--ms-count-clear-font-size** - Count clear button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-count-clear-icon-size** - Count clear X icon size (mask SVG) _(default: undefined)_\n- **--ms-count-clear-border-radius** - Count clear button border radius _(default: undefined)_\n- **--ms-count-clear-bg-hover** - Count clear button hover background _(default: undefined)_\n- **--ms-count-clear-color-hover** - Count clear button hover color _(default: undefined)_\n- **--ms-icon-clear** - Clear icon as CSS url() to a mask-friendly SVG; defaults to var(--ms-icon-remove) _(default: undefined)_\n- **--ms-tooltip-bg** - Tooltip background _(default: undefined)_\n- **--ms-tooltip-text-color** - Tooltip text color _(default: undefined)_\n- **--ms-tooltip-color** - Tooltip color _(default: undefined)_\n- **--ms-tooltip-padding** - Tooltip padding _(default: undefined)_\n- **--ms-tooltip-border-radius** - Tooltip border radius _(default: undefined)_\n- **--ms-tooltip-font-size** - Tooltip font size _(default: undefined)_\n- **--ms-tooltip-max-width** - Tooltip max width _(default: undefined)_\n- **--ms-tooltip-shadow** - Tooltip shadow _(default: undefined)_\n- **--ms-tooltip-z-index** - Tooltip z-index _(default: undefined)_\n- **--ms-z-index-popover** - Popover z-index _(default: undefined)_\n- **--ms-selected-popover-width** - Selected popover width _(default: undefined)_\n- **--ms-selected-popover-max-height** - Selected popover max height _(default: undefined)_\n- **--ms-selected-popover-border** - Selected popover border _(default: undefined)_\n- **--ms-selected-popover-border-radius** - Selected popover border radius _(default: undefined)_\n- **--ms-selected-popover-box-shadow** - Selected popover shadow _(default: undefined)_\n- **--ms-selected-popover-bg** - Selected popover background _(default: undefined)_\n- **--ms-selected-popover-border-color** - Selected popover border color _(default: undefined)_\n- **--ms-selected-popover-header-padding** - Popover header padding _(default: undefined)_\n- **--ms-selected-popover-header-bg** - Popover header background _(default: undefined)_\n- **--ms-selected-popover-header-border-bottom** - Popover header border _(default: undefined)_\n- **--ms-selected-popover-header-font-size** - Popover header font size _(default: undefined)_\n- **--ms-selected-popover-header-font-weight** - Popover header font weight _(default: undefined)_\n- **--ms-selected-popover-header-color** - Popover header color _(default: undefined)_\n- **--ms-selected-popover-header-border-color** - Popover header border color _(default: undefined)_\n- **--ms-popover-close-size** - Popover close button size _(default: undefined)_\n- **--ms-selected-popover-close-bg** - Popover close button background _(default: undefined)_\n- **--ms-selected-popover-close-color** - Popover close button color _(default: undefined)_\n- **--ms-selected-popover-close-font-size** - Popover close button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-selected-popover-close-icon-size** - Popover close X icon size (mask SVG) _(default: undefined)_\n- **--ms-selected-popover-close-border-radius** - Popover close button border radius _(default: undefined)_\n- **--ms-selected-popover-close-bg-hover** - Popover close button hover background _(default: undefined)_\n- **--ms-selected-popover-close-color-hover** - Popover close button hover color _(default: undefined)_\n- **--ms-selected-popover-body-gap** - Popover body gap _(default: undefined)_\n- **--ms-selected-popover-body-padding** - Popover body padding _(default: undefined)_\n- **--ms-selected-popover-body-max-height** - Popover body max height _(default: undefined)_\n- **--ms-font-size-2xs** - Extra extra small font size _(default: undefined)_\n- **--ms-font-size-xs** - Extra small font size _(default: undefined)_\n- **--ms-font-size-sm** - Small font size _(default: undefined)_\n- **--ms-font-size-base** - Base font size _(default: undefined)_\n- **--ms-font-size-lg** - Large font size _(default: undefined)_\n- **--ms-font-weight-normal** - Normal font weight _(default: undefined)_\n- **--ms-font-weight-medium** - Medium font weight _(default: undefined)_\n- **--ms-font-weight-semibold** - Semibold font weight _(default: undefined)_\n- **--ms-line-height-none** - No line height (1) _(default: undefined)_\n- **--ms-line-height-tight** - Tight line height _(default: undefined)_\n- **--ms-line-height-normal** - Normal line height _(default: undefined)_\n- **--ms-line-height-relaxed** - Relaxed line height _(default: undefined)_\n- **--ms-border-radius-sm** - Small border radius _(default: undefined)_\n- **--ms-border-radius-md** - Medium border radius _(default: undefined)_\n- **--ms-border-radius-lg** - Large border radius _(default: undefined)_\n- **--ms-border-radius** - Default border radius _(default: undefined)_\n- **--ms-spacing-xs** - Extra small spacing _(default: undefined)_\n- **--ms-spacing-sm** - Small spacing _(default: undefined)_\n- **--ms-spacing-md** - Medium spacing _(default: undefined)_\n- **--ms-spacing-lg** - Large spacing _(default: undefined)_\n- **--ms-transition-fast** - Fast transition duration _(default: undefined)_\n- **--ms-transition-normal** - Normal transition duration _(default: undefined)_\n- **--ms-easing-snappy** - Snappy easing function _(default: undefined)_\n- **--ms-placeholder-opacity** - Placeholder opacity _(default: undefined)_\n- **--ms-disabled-input-opacity** - Disabled input opacity _(default: undefined)_\n- **--ms-scrollbar-width** - Scrollbar width _(default: undefined)_\n- **--ms-scrollbar-track-bg** - Scrollbar track background _(default: undefined)_\n- **--ms-scrollbar-thumb-bg** - Scrollbar thumb background _(default: undefined)_\n- **--ms-scrollbar-thumb-bg-hover** - Scrollbar thumb hover background _(default: undefined)_\n- **--ms-scrollbar-thumb-border-radius** - Scrollbar thumb border radius _(default: undefined)_\n- **--ms-debug-bg** - Debug panel background _(default: undefined)_\n- **--ms-debug-border-color** - Debug panel border _(default: undefined)_\n- **--ms-debug-text-color** - Debug panel text _(default: undefined)_\n- **--ms-debug-border-radius** - Debug panel corner radius _(default: undefined)_\n- **--ms-debug-summary-color** - Debug section heading color _(default: undefined)_\n- **--ms-debug-summary-bg-hover** - Debug section heading hover background _(default: undefined)_\n- **--ms-debug-summary-outline-color** - Debug section heading focus outline _(default: undefined)_\n- **--ms-debug-summary-border-radius** - Debug section heading corner radius _(default: undefined)_\n- **--ms-debug-stats-bg** - Debug stats nested panel background _(default: undefined)_\n- **--ms-debug-stats-border-radius** - Debug stats nested panel corner radius _(default: undefined)_\n- **--ms-debug-bullet-color** - Debug stat bullet marker color _(default: undefined)_\n- **--ms-transform-rotate-180** - 180 degree rotation _(default: undefined)_\n- **--ms-transform-scale-hover** - Hover scale transform _(default: undefined)_\n- **--ms-transform-scale-active** - Active scale transform _(default: undefined)_\n- **--ms-order-first** - Order first (-1) _(default: undefined)_",
+          "description": "\n---\n\n\n### **Events:**\n - **select** - An option was selected. `detail.option` is the selected option; `detail.selectedOptions`/`detail.selectedValues` are the full selection.\n- **deselect** - An option was removed from the selection. `detail.option` is that option.\n- **change** - The selection changed. `detail.selectedOptions`/`detail.selectedValues` are the full selection.\n- **add** - The user chose to create a new option from the typed text (via the \"add new\" prompt or Enter) — requires `allow-add-new`. `detail.value` is the typed text; `detail.option` is the created item when `addNewCallback` produced one.\n- **ready** - The picker was built and painted for the first time (once per element lifetime). Fires right after the first build — synchronously during upgrade for a normal element, or when the render gate is released (`el.ready()` / removing `defer`) for a deferred one. No detail.\n\n### **Methods:**\n - **formResetCallback(): _void_** - Called by the browser when the surrounding <form> is reset. Clears the\r\npicker's selection so the control participates in the standard reset.\n\n\n\n\n\n\n\n- **showMessage(content: _string | HTMLElement_, opts: _MessageOptions_): _void_** - Surface a transient message (\"toast\") on top of the component — visible even in the\r\nfullscreen overlay, where page-level UI is hidden behind the sheet. Content is text or\r\nan element; `opts.variant` sets the tone and `opts.duration` the auto-dismiss (0 =\r\nsticky). Also reached automatically when a `beforeSelect`/`beforeDeselect` callback\r\nreturns a reason string.\n- **hideMessage(): _void_** - Dismiss the transient message shown by showMessage, if any.\n- **clearSearch(): _void_** - Clear the search box and restore the full option list (does not touch the selection — use\r\nclearAll for that). Pair with scrollToValue to reveal then scroll to an option\r\na search had filtered out: `el.clearSearch(); el.scrollToValue(v)`.\n- **search(term: _string_): _void_** - Programmatically set the search text and filter, as if the user typed it (runs\r\n`beforeSearchCallback` / `minSearchLength` / async `searchCallback`). Does not open the dropdown\r\n— call open if you want it visible. Pass `''` to clear (same as clearSearch).\n- **scrollToIndex(index: _number_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll the open dropdown to the option at `index` (into the current filtered list). Returns\r\nfalse if closed or out of range. Deferred internally so `el.open(); el.scrollToIndex(i)` works.\n- **scrollToValue(value: _string | number_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll the open dropdown to the option with this `value`. Returns false if it isn't in the\r\ncurrently visible list (filtered out by search, or under a collapsed tree branch) — call\r\nclearSearch / expand first.\n- **scrollToGroup(name: _string_, opts: _{ block?: ScrollLogicalPosition }_): _boolean_** - Scroll to a group: its header in standard rendering, or the group's first option in\r\nvirtual-scroll mode (no headers there). Returns false in tree mode or if the group is empty\r\nin the current filtered list.\n- **open(): _void_** - Open the dropdown.\n- **close(): _void_** - Close the dropdown.\n- **toggle(): _void_** - Toggle the dropdown open/closed.\n- **ready(): _void_** - Release the `defer` render gate: build the picker now (once), with every\r\noption, callback and listener wired while deferred already in place. No-op\r\nwhen the element wasn't deferred or is already built. `flush()` first so a\r\nsynchronous `el.options = …; el.customStylesCallback = …; el.ready()` lands\r\nthose pending writes in the single build rather than after it. Latched — the\r\ngate never re-closes. Fires the `ready` event on the first build.\n\n### **CSS Properties:**\n - **--ms-rem** - Base sizing unit for proportional scaling (default: 10px) _(default: undefined)_\n- **--ms-accent-color** - Primary accent color _(default: undefined)_\n- **--ms-accent-color-hover** - Accent color on hover _(default: undefined)_\n- **--ms-accent-color-active** - Accent color when pressed _(default: undefined)_\n- **--ms-accent-color-light** - Light accent background _(default: undefined)_\n- **--ms-accent-color-light-hover** - Light accent hover _(default: undefined)_\n- **--ms-text-color-1** - Primary text color _(default: undefined)_\n- **--ms-text-color-2** - Secondary text color _(default: undefined)_\n- **--ms-text-color-3** - Tertiary text color _(default: undefined)_\n- **--ms-text-color-4** - Quaternary text color _(default: undefined)_\n- **--ms-text-color-on-accent** - Text on accent backgrounds _(default: undefined)_\n- **--ms-text-primary** - Legacy alias for text-color-1 _(default: undefined)_\n- **--ms-text-secondary** - Legacy alias for text-color-3 _(default: undefined)_\n- **--ms-primary-bg** - Hover/focus background (options, action buttons, counter); reads --base-hover-bg _(default: undefined)_\n- **--ms-primary-bg-hover** - Active/stronger background (counter badge text); reads --base-active-bg _(default: undefined)_\n- **--ms-border-color** - Default border color _(default: undefined)_\n- **--ms-border** - Full border shorthand _(default: undefined)_\n- **--ms-input-bg** - Input field background _(default: undefined)_\n- **--ms-input-color** - Input text color _(default: undefined)_\n- **--ms-input-border** - Input border _(default: undefined)_\n- **--ms-input-border-hover** - Input border on hover _(default: undefined)_\n- **--ms-input-border-focus** - Input border when focused _(default: undefined)_\n- **--ms-input-placeholder-color** - Placeholder text color _(default: undefined)_\n- **--ms-input-bg-disabled** - Disabled input background _(default: undefined)_\n- **--ms-input-height** - Input height _(default: undefined)_\n- **--ms-input-font-size** - Input font size _(default: undefined)_\n- **--ms-input-border-width** - Input border width _(default: undefined)_\n- **--ms-input-border-radius** - Input border radius _(default: undefined)_\n- **--ms-input-text** - Input text color _(default: undefined)_\n- **--ms-toggle-color** - Toggle icon color _(default: undefined)_\n- **--ms-toggle-icon-color** - Toggle icon color (semantic) _(default: undefined)_\n- **--ms-toggle-icon-color-open** - Toggle icon color when open _(default: undefined)_\n- **--ms-counter-padding** - Counter badge padding _(default: undefined)_\n- **--ms-counter-bg** - Counter badge background _(default: undefined)_\n- **--ms-counter-color** - Counter badge text color _(default: undefined)_\n- **--ms-counter-font-size** - Counter badge font size _(default: undefined)_\n- **--ms-counter-font-weight** - Counter badge font weight _(default: undefined)_\n- **--ms-counter-border-radius** - Counter badge border radius _(default: undefined)_\n- **--ms-counter-bg-hover** - Counter badge hover background _(default: undefined)_\n- **--ms-counter-badge-bg** - Counter badge semantic background _(default: undefined)_\n- **--ms-counter-badge-bg-hover** - Counter badge semantic hover _(default: undefined)_\n- **--ms-counter-badge-color** - Counter badge semantic color _(default: undefined)_\n- **--ms-hint-padding** - Floating hint padding _(default: undefined)_\n- **--ms-hint-border** - Floating hint border _(default: undefined)_\n- **--ms-hint-border-radius** - Floating hint border radius _(default: undefined)_\n- **--ms-hint-box-shadow** - Floating hint shadow _(default: undefined)_\n- **--ms-hint-font-size** - Floating hint font size _(default: undefined)_\n- **--ms-hint-bg** - Floating hint background _(default: undefined)_\n- **--ms-hint-color** - Floating hint text color _(default: undefined)_\n- **--ms-hint-border-color** - Floating hint border color _(default: undefined)_\n- **--ms-dropdown-bg** - Dropdown background _(default: undefined)_\n- **--ms-dropdown-text-color** - Dropdown text color _(default: undefined)_\n- **--ms-dropdown-border** - Dropdown border _(default: undefined)_\n- **--ms-dropdown-border-color** - Dropdown border color _(default: undefined)_\n- **--ms-dropdown-border-radius** - Dropdown border radius _(default: undefined)_\n- **--ms-dropdown-box-shadow** - Dropdown shadow _(default: undefined)_\n- **--ms-dropdown-box-shadow-semantic** - Dropdown semantic shadow _(default: undefined)_\n- **--ms-dropdown-width** - Options dropdown width (defaults to the input width; also set via the dropdown-width attribute) _(default: undefined)_\n- **--ms-options-max-height** - Options list max height _(default: undefined)_\n- **--ms-z-index-dropdown** - Dropdown z-index _(default: undefined)_\n- **--ms-z-index-sticky** - Sticky elements z-index _(default: undefined)_\n- **--ms-actions-gap** - Actions row gap _(default: undefined)_\n- **--ms-actions-padding** - Actions row padding _(default: undefined)_\n- **--ms-actions-border-bottom** - Actions row border _(default: undefined)_\n- **--ms-actions-bg** - Actions row background _(default: undefined)_\n- **--ms-actions-border-color** - Actions row border color _(default: undefined)_\n- **--ms-action-btn-padding** - Action button padding _(default: undefined)_\n- **--ms-action-btn-font-size** - Action button font size _(default: undefined)_\n- **--ms-action-btn-border** - Action button border _(default: undefined)_\n- **--ms-action-btn-border-radius** - Action button border radius _(default: undefined)_\n- **--ms-action-btn-bg** - Action button background _(default: undefined)_\n- **--ms-action-btn-color** - Action button color _(default: undefined)_\n- **--ms-action-btn-bg-hover** - Action button hover background _(default: undefined)_\n- **--ms-action-btn-border-color-hover** - Action button hover border _(default: undefined)_\n- **--ms-action-button-bg** - Semantic action button background _(default: undefined)_\n- **--ms-action-button-bg-hover** - Semantic action button hover _(default: undefined)_\n- **--ms-action-button-border-color** - Semantic action button border _(default: undefined)_\n- **--ms-action-button-border-color-hover** - Semantic action button hover border _(default: undefined)_\n- **--ms-action-button-color** - Semantic action button color _(default: undefined)_\n- **--ms-options-padding** - Options container padding _(default: undefined)_\n- **--ms-group-border-top** - Group border top _(default: undefined)_\n- **--ms-group-margin-top** - Group margin top _(default: undefined)_\n- **--ms-group-padding-top** - Group padding top _(default: undefined)_\n- **--ms-group-border-color** - Group border color _(default: undefined)_\n- **--ms-group-label-padding** - Group label padding _(default: undefined)_\n- **--ms-group-label-font-size** - Group label font size _(default: undefined)_\n- **--ms-group-label-font-weight** - Group label font weight _(default: undefined)_\n- **--ms-group-label-color** - Group label color _(default: undefined)_\n- **--ms-group-label-transform** - Group label text transform _(default: undefined)_\n- **--ms-group-label-letter-spacing** - Group label letter spacing _(default: undefined)_\n- **--ms-option-gap** - Option content gap _(default: undefined)_\n- **--ms-option-padding** - Option padding _(default: undefined)_\n- **--ms-option-padding-h** - Option horizontal padding _(default: undefined)_\n- **--ms-option-color** - Option text color _(default: undefined)_\n- **--ms-option-bg** - Option background _(default: undefined)_\n- **--ms-option-bg-hover** - Option hover background _(default: undefined)_\n- **--ms-option-bg-focused** - Option focused background _(default: undefined)_\n- **--ms-option-outline-focused** - Option focus outline _(default: undefined)_\n- **--ms-option-focus-outline-offset** - Option focus outline offset _(default: undefined)_\n- **--ms-option-bg-matched** - Matched option background _(default: undefined)_\n- **--ms-option-border-matched** - Matched option border _(default: undefined)_\n- **--ms-option-bg-selected** - Selected option background _(default: undefined)_\n- **--ms-option-text-color** - Option text color (semantic) _(default: undefined)_\n- **--ms-option-color-hover** - Option hover color _(default: undefined)_\n- **--ms-option-color-focused** - Option focused color _(default: undefined)_\n- **--ms-option-outline-color-focused** - Option focus outline color _(default: undefined)_\n- **--ms-option-color-matched** - Matched option color _(default: undefined)_\n- **--ms-option-border-matched-color** - Matched option border color _(default: undefined)_\n- **--ms-option-bg-focused-hover** - Focused option hover background _(default: undefined)_\n- **--ms-option-bg-matched-hover** - Matched option hover background _(default: undefined)_\n- **--ms-option-bg-selected-focused** - Selected focused background _(default: undefined)_\n- **--ms-option-bg-selected-matched** - Selected matched background _(default: undefined)_\n- **--ms-option-disabled-bg** - Disabled option background _(default: undefined)_\n- **--ms-option-bg-disabled-selected** - Disabled selected background _(default: undefined)_\n- **--ms-disabled-opacity** - Disabled option opacity _(default: undefined)_\n- **--ms-option-content-gap** - Option content gap _(default: undefined)_\n- **--ms-option-icon-size** - Option icon size _(default: undefined)_\n- **--ms-option-icon-font-size** - Option icon font size _(default: undefined)_\n- **--ms-option-title-font-size** - Option title font size _(default: undefined)_\n- **--ms-option-title-color** - Option title color _(default: undefined)_\n- **--ms-option-subtitle-margin-top** - Option subtitle margin _(default: undefined)_\n- **--ms-option-subtitle-font-size** - Option subtitle font size _(default: undefined)_\n- **--ms-option-subtitle-line-height** - Option subtitle line height _(default: undefined)_\n- **--ms-option-subtitle-color** - Option subtitle color _(default: undefined)_\n- **--ms-option-mark-bg** - Search match highlight background _(default: undefined)_\n- **--ms-option-mark-color** - Search match highlight color _(default: undefined)_\n- **--ms-option-mark-font-weight** - Search match highlight weight _(default: undefined)_\n- **--ms-checkbox-margin-top** - Checkbox margin top _(default: undefined)_\n- **--ms-checkbox-margin-right** - Checkbox margin right _(default: undefined)_\n- **--ms-checkbox-margin-bottom** - Checkbox margin bottom _(default: undefined)_\n- **--ms-checkbox-margin-left** - Checkbox margin left _(default: undefined)_\n- **--ms-checkbox-size** - Checkbox size _(default: undefined)_\n- **--ms-checkbox-scale** - Checkbox scale _(default: undefined)_\n- **--ms-checkbox-align** - Checkbox alignment _(default: undefined)_\n- **--ms-checkbox-bg** - Checkbox background _(default: undefined)_\n- **--ms-checkbox-border** - Checkbox border _(default: undefined)_\n- **--ms-checkbox-border-radius** - Checkbox border radius _(default: undefined)_\n- **--ms-checkbox-checked-bg** - Checked checkbox background _(default: undefined)_\n- **--ms-checkbox-checked-border** - Checked checkbox border _(default: undefined)_\n- **--ms-checkbox-checkmark-color** - Checkmark color _(default: undefined)_\n- **--ms-checkbox-hover-border-color** - Checkbox hover border _(default: undefined)_\n- **--ms-checkbox-disabled-bg** - Disabled checkbox background _(default: undefined)_\n- **--ms-checkbox-disabled-border** - Disabled checkbox border _(default: undefined)_\n- **--ms-checkbox-checked-bg-hover** - Checked checkbox hover background _(default: undefined)_\n- **--ms-checkbox-checked-border-color-hover** - Checked checkbox hover border _(default: undefined)_\n- **--ms-state-min-height** - Shared min-height for the empty and loading states so the dropdown doesn't resize when swapping between them _(default: undefined)_\n- **--ms-empty-padding** - Empty state padding _(default: undefined)_\n- **--ms-empty-font-size** - Empty state font size _(default: undefined)_\n- **--ms-empty-color** - Empty state text color _(default: undefined)_\n- **--ms-loader-padding** - Loader padding _(default: undefined)_\n- **--ms-loader-gap** - Loader gap _(default: undefined)_\n- **--ms-loading-text-font-size** - Loading text font size _(default: undefined)_\n- **--ms-loading-text-color** - Loading text color _(default: undefined)_\n- **--ms-loading-color** - Loading color (semantic) _(default: undefined)_\n- **--ms-badges-gap** - Badges container gap _(default: undefined)_\n- **--ms-badges-margin-bottom** - Badges margin bottom _(default: undefined)_\n- **--ms-badges-margin-top** - Badges margin top _(default: undefined)_\n- **--ms-badges-margin-left** - Badges margin left _(default: undefined)_\n- **--ms-badges-margin-right** - Badges margin right _(default: undefined)_\n- **--ms-badge-gap** - Badge internal gap _(default: undefined)_\n- **--ms-badge-height** - Badge height _(default: undefined)_\n- **--ms-badge-font-size** - Badge font size _(default: undefined)_\n- **--ms-badge-font-weight** - Badge font weight _(default: undefined)_\n- **--ms-badge-border-radius** - Badge border radius _(default: undefined)_\n- **--ms-badge-bg** - Badge background _(default: undefined)_\n- **--ms-badge-bg-hover** - Badge hover background _(default: undefined)_\n- **--ms-badge-bg-active** - Badge active background _(default: undefined)_\n- **--ms-badge-text-padding** - Badge text padding _(default: undefined)_\n- **--ms-badge-text-bg** - Badge text background _(default: undefined)_\n- **--ms-badge-text-color** - Badge text color _(default: undefined)_\n- **--ms-badge-text-border** - Badge text border _(default: undefined)_\n- **--ms-badge-text-bg-hover** - Badge text hover background _(default: undefined)_\n- **--ms-badge-text-color-hover** - Badge text hover color _(default: undefined)_\n- **--ms-badge-remove-width** - Badge remove button width _(default: undefined)_\n- **--ms-badge-remove-bg** - Badge remove button background _(default: undefined)_\n- **--ms-badge-remove-color** - Badge remove button color _(default: undefined)_\n- **--ms-badge-remove-border** - Badge remove button border _(default: undefined)_\n- **--ms-badge-remove-font-size** - Badge remove button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-badge-remove-icon-size** - Badge remove X icon size (mask SVG) _(default: undefined)_\n- **--ms-badge-remove-bg-hover** - Badge remove button hover background _(default: undefined)_\n- **--ms-badge-remove-box-shadow-focus** - Badge remove button focus shadow _(default: undefined)_\n- **--ms-icon-remove** - Remove icon as CSS url() to a mask-friendly SVG; color comes from currentColor _(default: undefined)_\n- **--ms-icon-filter** - Funnel glyph (fullscreen search-mode toggle); chains to --base-icon-filter _(default: undefined)_\n- **--ms-icon-check** - Checkmark glyph (mask) for a checked checkbox/option; chains to --base-icon-check _(default: undefined)_\n- **--ms-icon-indeterminate** - Dash glyph (mask) for a tri-state/partial checkbox; chains to --base-icon-indeterminate _(default: undefined)_\n- **--ms-icon-check-size** - mask-size for the checkmark/dash glyph inside the checkbox box; chains to --base-icon-check-size (default 68%, the same knob as pure-admin's .pa-checkbox) _(default: undefined)_\n- **--ms-badge-counter-bg** - Counter badge background _(default: undefined)_\n- **--ms-badge-counter-border** - Counter badge border _(default: undefined)_\n- **--ms-badge-counter-border-color** - Counter badge border color _(default: undefined)_\n- **--ms-badge-counter-border-radius** - Counter badge border radius _(default: undefined)_\n- **--ms-badge-counter-text-color** - Counter badge text color _(default: undefined)_\n- **--ms-badge-counter-text-bg** - Counter badge text background _(default: undefined)_\n- **--ms-badge-counter-remove-bg** - Counter badge remove background _(default: undefined)_\n- **--ms-badge-counter-remove-color** - Counter badge remove color _(default: undefined)_\n- **--ms-badge-counter-remove-bg-hover** - Counter badge remove hover background _(default: undefined)_\n- **--ms-more-badge-bg** - More badge background _(default: undefined)_\n- **--ms-more-badge-hover-bg** - More badge hover background _(default: undefined)_\n- **--ms-more-badge-active-bg** - More badge active background _(default: undefined)_\n- **--ms-count-display-margin-bottom** - Count display margin bottom _(default: undefined)_\n- **--ms-count-display-margin-top** - Count display margin top _(default: undefined)_\n- **--ms-count-display-margin-left** - Count display margin left _(default: undefined)_\n- **--ms-count-display-margin-right** - Count display margin right _(default: undefined)_\n- **--ms-counter-wrapper-bg** - Counter wrapper background _(default: undefined)_\n- **--ms-counter-wrapper-border** - Counter wrapper border _(default: undefined)_\n- **--ms-counter-wrapper-border-radius** - Counter wrapper border radius _(default: undefined)_\n- **--ms-counter-wrapper-padding** - Counter wrapper padding _(default: undefined)_\n- **--ms-counter-wrapper-gap** - Counter wrapper gap _(default: undefined)_\n- **--ms-counter-wrapper-bg-hover** - Counter wrapper hover background _(default: undefined)_\n- **--ms-counter-wrapper-border-color** - Counter wrapper border color _(default: undefined)_\n- **--ms-counter-wrapper-border-color-hover** - Counter wrapper hover border _(default: undefined)_\n- **--ms-count-text-bg** - Count text background _(default: undefined)_\n- **--ms-count-text-border** - Count text border _(default: undefined)_\n- **--ms-count-text-font-size** - Count text font size _(default: undefined)_\n- **--ms-count-text-color** - Count text color _(default: undefined)_\n- **--ms-count-clear-size** - Count clear button size _(default: undefined)_\n- **--ms-count-clear-bg** - Count clear button background _(default: undefined)_\n- **--ms-count-clear-color** - Count clear button color _(default: undefined)_\n- **--ms-count-clear-font-size** - Count clear button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-count-clear-icon-size** - Count clear X icon size (mask SVG) _(default: undefined)_\n- **--ms-count-clear-border-radius** - Count clear button border radius _(default: undefined)_\n- **--ms-count-clear-bg-hover** - Count clear button hover background _(default: undefined)_\n- **--ms-count-clear-color-hover** - Count clear button hover color _(default: undefined)_\n- **--ms-icon-clear** - Clear icon as CSS url() to a mask-friendly SVG; defaults to var(--ms-icon-remove) _(default: undefined)_\n- **--ms-tooltip-bg** - Tooltip background _(default: undefined)_\n- **--ms-tooltip-text-color** - Tooltip text color _(default: undefined)_\n- **--ms-tooltip-color** - Tooltip color _(default: undefined)_\n- **--ms-tooltip-padding** - Tooltip padding _(default: undefined)_\n- **--ms-tooltip-border-radius** - Tooltip border radius _(default: undefined)_\n- **--ms-tooltip-font-size** - Tooltip font size _(default: undefined)_\n- **--ms-tooltip-max-width** - Tooltip max width _(default: undefined)_\n- **--ms-tooltip-shadow** - Tooltip shadow _(default: undefined)_\n- **--ms-tooltip-z-index** - Tooltip z-index _(default: undefined)_\n- **--ms-z-index-popover** - Popover z-index _(default: undefined)_\n- **--ms-selected-popover-width** - Selected popover width _(default: undefined)_\n- **--ms-selected-popover-max-height** - Selected popover max height _(default: undefined)_\n- **--ms-selected-popover-border** - Selected popover border _(default: undefined)_\n- **--ms-selected-popover-border-radius** - Selected popover border radius _(default: undefined)_\n- **--ms-selected-popover-box-shadow** - Selected popover shadow _(default: undefined)_\n- **--ms-selected-popover-bg** - Selected popover background _(default: undefined)_\n- **--ms-selected-popover-border-color** - Selected popover border color _(default: undefined)_\n- **--ms-selected-popover-header-padding** - Popover header padding _(default: undefined)_\n- **--ms-selected-popover-header-bg** - Popover header background _(default: undefined)_\n- **--ms-selected-popover-header-border-bottom** - Popover header border _(default: undefined)_\n- **--ms-selected-popover-header-font-size** - Popover header font size _(default: undefined)_\n- **--ms-selected-popover-header-font-weight** - Popover header font weight _(default: undefined)_\n- **--ms-selected-popover-header-color** - Popover header color _(default: undefined)_\n- **--ms-selected-popover-header-border-color** - Popover header border color _(default: undefined)_\n- **--ms-popover-close-size** - Popover close button size _(default: undefined)_\n- **--ms-selected-popover-close-bg** - Popover close button background _(default: undefined)_\n- **--ms-selected-popover-close-color** - Popover close button color _(default: undefined)_\n- **--ms-selected-popover-close-font-size** - Popover close button font size (unused since 1.10.0 — kept for backward-compat) _(default: undefined)_\n- **--ms-selected-popover-close-icon-size** - Popover close X icon size (mask SVG) _(default: undefined)_\n- **--ms-selected-popover-close-border-radius** - Popover close button border radius _(default: undefined)_\n- **--ms-selected-popover-close-bg-hover** - Popover close button hover background _(default: undefined)_\n- **--ms-selected-popover-close-color-hover** - Popover close button hover color _(default: undefined)_\n- **--ms-selected-popover-body-gap** - Popover body gap _(default: undefined)_\n- **--ms-selected-popover-body-padding** - Popover body padding _(default: undefined)_\n- **--ms-selected-popover-body-max-height** - Popover body max height _(default: undefined)_\n- **--ms-font-size-2xs** - Extra extra small font size _(default: undefined)_\n- **--ms-font-size-xs** - Extra small font size _(default: undefined)_\n- **--ms-font-size-sm** - Small font size _(default: undefined)_\n- **--ms-font-size-base** - Base font size _(default: undefined)_\n- **--ms-font-size-lg** - Large font size _(default: undefined)_\n- **--ms-font-weight-normal** - Normal font weight _(default: undefined)_\n- **--ms-font-weight-medium** - Medium font weight _(default: undefined)_\n- **--ms-font-weight-semibold** - Semibold font weight _(default: undefined)_\n- **--ms-line-height-none** - No line height (1) _(default: undefined)_\n- **--ms-line-height-tight** - Tight line height _(default: undefined)_\n- **--ms-line-height-normal** - Normal line height _(default: undefined)_\n- **--ms-line-height-relaxed** - Relaxed line height _(default: undefined)_\n- **--ms-border-radius-sm** - Small border radius _(default: undefined)_\n- **--ms-border-radius-md** - Medium border radius _(default: undefined)_\n- **--ms-border-radius-lg** - Large border radius _(default: undefined)_\n- **--ms-border-radius** - Default border radius _(default: undefined)_\n- **--ms-spacing-xs** - Extra small spacing _(default: undefined)_\n- **--ms-spacing-sm** - Small spacing _(default: undefined)_\n- **--ms-spacing-md** - Medium spacing _(default: undefined)_\n- **--ms-spacing-lg** - Large spacing _(default: undefined)_\n- **--ms-transition-fast** - Fast transition duration _(default: undefined)_\n- **--ms-transition-normal** - Normal transition duration _(default: undefined)_\n- **--ms-easing-snappy** - Snappy easing function _(default: undefined)_\n- **--ms-placeholder-opacity** - Placeholder opacity _(default: undefined)_\n- **--ms-disabled-input-opacity** - Disabled input opacity _(default: undefined)_\n- **--ms-scrollbar-width** - Scrollbar width _(default: undefined)_\n- **--ms-scrollbar-track-bg** - Scrollbar track background _(default: undefined)_\n- **--ms-scrollbar-thumb-bg** - Scrollbar thumb background _(default: undefined)_\n- **--ms-scrollbar-thumb-bg-hover** - Scrollbar thumb hover background _(default: undefined)_\n- **--ms-scrollbar-thumb-border-radius** - Scrollbar thumb border radius _(default: undefined)_\n- **--ms-debug-bg** - Debug panel background _(default: undefined)_\n- **--ms-debug-border-color** - Debug panel border _(default: undefined)_\n- **--ms-debug-text-color** - Debug panel text _(default: undefined)_\n- **--ms-debug-border-radius** - Debug panel corner radius _(default: undefined)_\n- **--ms-debug-summary-color** - Debug section heading color _(default: undefined)_\n- **--ms-debug-summary-bg-hover** - Debug section heading hover background _(default: undefined)_\n- **--ms-debug-summary-outline-color** - Debug section heading focus outline _(default: undefined)_\n- **--ms-debug-summary-border-radius** - Debug section heading corner radius _(default: undefined)_\n- **--ms-debug-stats-bg** - Debug stats nested panel background _(default: undefined)_\n- **--ms-debug-stats-border-radius** - Debug stats nested panel corner radius _(default: undefined)_\n- **--ms-debug-bullet-color** - Debug stat bullet marker color _(default: undefined)_\n- **--ms-transform-rotate-180** - 180 degree rotation _(default: undefined)_\n- **--ms-transform-scale-hover** - Hover scale transform _(default: undefined)_\n- **--ms-transform-scale-active** - Active scale transform _(default: undefined)_\n- **--ms-order-first** - Order first (-1) _(default: undefined)_",
           "doc-url": "",
           "attributes": [
             {
@@ -158,10 +158,10 @@
             },
             {
               "name": "checkbox-mode",
-              "description": "Tree checkbox interaction.\n- `independent` (default) — toggles only the clicked node.\n- `cascade` — checks a node whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches.\n\nTree + multiple only.",
+              "description": "Tree checkbox interaction.\n- `cascade` (default) — checks a node's whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches. This is what most tree-select UIs do, so it's the default.\n- `independent` — toggles only the clicked node, ignoring ancestors/descendants.\n\nTree + multiple only — has no effect on flat lists or single-select (there is no subtree to cascade into).",
               "value": {
                 "type": "'independent' | 'cascade'",
-                "default": "'independent'"
+                "default": "'cascade'"
               }
             },
             {
@@ -172,6 +172,11 @@
                 "default": "'rolled-up'"
               }
             },
+            {
+              "name": "group-select-mode",
+              "description": "Group-header selection in a FLAT (non-tree) grouped, multi-select list.\n- `none` (default) — group headers are inert labels.\n- `cascade` — each header shows a tristate checkbox that checks/unchecks all of that group's currently-visible members; a partially-selected group reads indeterminate. The group itself is never a selected value (getValue / badges / form carry member values only).\n\nFlat + multiple only — no effect in tree mode (use `checkbox-mode`) or single-select.",
+              "value": { "type": "'none' | 'cascade'", "default": "'none'" }
+            },
             {
               "name": "badges-display-mode",
               "description": "How the current selection is shown in the control.",
@@ -193,6 +198,19 @@
               "description": "How `badgesThreshold` is interpreted: collapse to a count badge, or keep partial badges + a \"more\" badge.",
               "value": { "type": "'count' | 'partial'", "default": "'count'" }
             },
+            {
+              "name": "selected-order",
+              "description": "Order of the CURRENTLY-SELECTED items where they are displayed — badges, partial mode (which items sit behind the \"+N more\" badge), and the selected-items popover. Display only: `getValue()`, the form output, and `getSelected()` keep as-selected (insertion) order, and the options dropdown is never reordered.\n- `as-selected` (default) — the order items were picked.\n- `label-asc` / `label-desc` — by the badge label, A→Z / Z→A (locale-aware).\n- `member` — by the `selected-order-member` property (or `getSelectedOrderCallback`); numeric keys sort numerically, everything else with a locale string compare.\n- `custom` — delegate to `selectedOrderCompareCallback`.",
+              "value": {
+                "type": "'as-selected' | 'label-asc' | 'label-desc' | 'member' | 'custom'",
+                "default": "'as-selected'"
+              }
+            },
+            {
+              "name": "selected-order-member",
+              "description": "Property name used as the sort key when `selected-order=\"member\"`. Sorts the SELECTED-items display only (not the dropdown). Overridden by `getSelectedOrderCallback`.",
+              "value": { "type": "string | null" }
+            },
             {
               "name": "search-input-mode",
               "description": "Search field mode: editable, read-only, or hidden.",
@@ -447,6 +465,11 @@
               "description": "Render an in-component debug panel.",
               "value": { "type": "boolean" }
             },
+            {
+              "name": "defer",
+              "description": "Hold the initial render. When the `defer` attribute is present on upgrade the component builds nothing (it only reserves space) — so options, callbacks (e.g. `customStylesCallback`) and event listeners can all be wired first, then released with `el.ready()` (or by removing the `defer` attribute, for server-driven frameworks). The release builds the picker ONCE with everything already in place, avoiding the upgrade-then-restyle flash. Absent (default): builds immediately on connect. Latched — once released the gate never re-closes.",
+              "value": { "type": "boolean" }
+            },
             {
               "name": "data-options",
               "description": "HTML-authoring source for the option list, parsed per `data-options-format`. Reactive: changing either attribute re-renders. Prefer the `options` property in JS; a set `options` property and declarative <option> children both win over this.",
@@ -487,6 +510,10 @@
             {
               "name": "add",
               "description": "The user chose to create a new option from the typed text (via the \"add new\" prompt or Enter) — requires `allow-add-new`. `detail.value` is the typed text; `detail.option` is the created item when `addNewCallback` produced one."
+            },
+            {
+              "name": "ready",
+              "description": "The picker was built and painted for the first time (once per element lifetime). Fires right after the first build — synchronously during upgrade for a normal element, or when the render gate is released (`el.ready()` / removing `defer`) for a deferred one. No detail."
             }
           ],
           "js": {
@@ -507,6 +534,10 @@
                 "name": "onAdd",
                 "type": "((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null"
               },
+              {
+                "name": "onReady",
+                "type": "((e: CustomEvent<undefined>) => void) | null"
+              },
               {
                 "name": "name",
                 "description": "Form field name (mirrors the `name` attribute → `formFieldId`).",
@@ -527,6 +558,11 @@
                 "description": "Whether the dropdown is currently open. Assigning opens/closes it.",
                 "type": "boolean"
               },
+              {
+                "name": "isReady",
+                "description": "Whether the picker has been built (the `ready` event has fired). False while a `defer` gate is still held.",
+                "type": "boolean"
+              },
               {
                 "name": "searchHint",
                 "description": "Small hint text shown beneath the search input.",
@@ -679,7 +715,7 @@
               },
               {
                 "name": "checkboxMode",
-                "description": "Tree checkbox interaction.\n- `independent` (default) — toggles only the clicked node.\n- `cascade` — checks a node whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches.\n\nTree + multiple only.",
+                "description": "Tree checkbox interaction.\n- `cascade` (default) — checks a node's whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches. This is what most tree-select UIs do, so it's the default.\n- `independent` — toggles only the clicked node, ignoring ancestors/descendants.\n\nTree + multiple only — has no effect on flat lists or single-select (there is no subtree to cascade into).",
                 "type": "'independent' | 'cascade'"
               },
               {
@@ -687,6 +723,11 @@
                 "description": "In `cascade` mode, which values a selection emits (badges / form / change):\n- `rolled-up` (default) — minimal cover: a fully-selected subtree collapses to its root; partially-selected branches emit their individually-checked descendants.\n- `leaves` — only the checked leaf-level nodes.\n- `all` — every fully-checked node (branches and leaves).",
                 "type": "'rolled-up' | 'leaves' | 'all'"
               },
+              {
+                "name": "groupSelectMode",
+                "description": "Group-header selection in a FLAT (non-tree) grouped, multi-select list.\n- `none` (default) — group headers are inert labels.\n- `cascade` — each header shows a tristate checkbox that checks/unchecks all of that group's currently-visible members; a partially-selected group reads indeterminate. The group itself is never a selected value (getValue / badges / form carry member values only).\n\nFlat + multiple only — no effect in tree mode (use `checkbox-mode`) or single-select.",
+                "type": "'none' | 'cascade'"
+              },
               {
                 "name": "badgesDisplayMode",
                 "description": "How the current selection is shown in the control.",
@@ -702,6 +743,16 @@
                 "description": "How `badgesThreshold` is interpreted: collapse to a count badge, or keep partial badges + a \"more\" badge.",
                 "type": "'count' | 'partial'"
               },
+              {
+                "name": "selectedOrder",
+                "description": "Order of the CURRENTLY-SELECTED items where they are displayed — badges, partial mode (which items sit behind the \"+N more\" badge), and the selected-items popover. Display only: `getValue()`, the form output, and `getSelected()` keep as-selected (insertion) order, and the options dropdown is never reordered.\n- `as-selected` (default) — the order items were picked.\n- `label-asc` / `label-desc` — by the badge label, A→Z / Z→A (locale-aware).\n- `member` — by the `selected-order-member` property (or `getSelectedOrderCallback`); numeric keys sort numerically, everything else with a locale string compare.\n- `custom` — delegate to `selectedOrderCompareCallback`.",
+                "type": "'as-selected' | 'label-asc' | 'label-desc' | 'member' | 'custom'"
+              },
+              {
+                "name": "selectedOrderMember",
+                "description": "Property name used as the sort key when `selected-order=\"member\"`. Sorts the SELECTED-items display only (not the dropdown). Overridden by `getSelectedOrderCallback`.",
+                "type": "string | null"
+              },
               {
                 "name": "searchInputMode",
                 "description": "Search field mode: editable, read-only, or hidden.",
@@ -932,6 +983,11 @@
                 "description": "Render an in-component debug panel.",
                 "type": "boolean"
               },
+              {
+                "name": "deferRender",
+                "description": "Hold the initial render. When the `defer` attribute is present on upgrade the component builds nothing (it only reserves space) — so options, callbacks (e.g. `customStylesCallback`) and event listeners can all be wired first, then released with `el.ready()` (or by removing the `defer` attribute, for server-driven frameworks). The release builds the picker ONCE with everything already in place, avoiding the upgrade-then-restyle flash. Absent (default): builds immediately on connect. Latched — once released the gate never re-closes.",
+                "type": "boolean"
+              },
               {
                 "name": "options",
                 "description": "The array of option objects to render. The JS API — assign `el.options` directly. For HTML authoring use the `data-options` attribute (parsed per `data-options-format`) or declarative <option> children; both feed the same list and take precedence over this property in the order: <option> children > property > data-options.",
@@ -1012,6 +1068,16 @@
                 "description": "Extra CSS class(es) for an option badge.",
                 "type": "(item: unknown) => string | string[]"
               },
+              {
+                "name": "getSelectedOrderCallback",
+                "description": "Sort key for the selected-items display when `selected-order=\"member\"` (overrides `selected-order-member`).",
+                "type": "(item: unknown) => string | number"
+              },
+              {
+                "name": "selectedOrderCompareCallback",
+                "description": "Comparator for the selected-items display when `selected-order=\"custom\"`.",
+                "type": "(a: unknown, b: unknown) => number"
+              },
               {
                 "name": "getIconCallback",
                 "description": "Icon for an option (overrides iconMember).",
@@ -1032,6 +1098,11 @@
                 "description": "Render the selected-count label.",
                 "type": "(count: number, moreCount?: number) => string"
               },
+              {
+                "name": "getCountLabelCallback",
+                "description": "Format the small count chip shared by the in-input counter and each group header count (default `[selected]`; e.g. `(s,t)=>`${s}/${t}``). One callback drives both.",
+                "type": "(selected: number, total: number) => string"
+              },
               {
                 "name": "getValueFormatCallback",
                 "description": "Serialize the selected values for form submission.",
@@ -1074,18 +1145,18 @@
               },
               {
                 "name": "renderGroupLabelContentCallback",
-                "description": "Customize a group label; may return an HTML string or element.",
-                "type": "(groupName: string) => string | HTMLElement"
+                "description": "Customize a group label; may return an HTML string or element. The second arg carries the group members + selection (e.g. `context.selectedCount`) so a custom header can show a per-group count.",
+                "type": "(groupName: string, context: GroupLabelRenderContext) => string | HTMLElement"
               },
               {
                 "name": "renderSelectedContentCallback",
-                "description": "Custom render for the whole selected area.",
-                "type": "(item: unknown) => string"
+                "description": "Custom render for the single-select selected value (2nd arg carries the presentation context).",
+                "type": "(item: unknown, context: SelectedContentRenderContext) => string"
               },
               {
                 "name": "renderSelectedItemContentCallback",
-                "description": "Custom render for one selected item.",
-                "type": "(item: unknown) => string | HTMLElement"
+                "description": "Custom render for one selected item in the popover (2nd arg is a BadgeContentRenderContext; isInPopover=true).",
+                "type": "(item: unknown, context: BadgeContentRenderContext) => string | HTMLElement"
               },
               {
                 "name": "customStylesCallback",
@@ -1139,6 +1210,10 @@
               {
                 "name": "add",
                 "description": "The user chose to create a new option from the typed text (via the \"add new\" prompt or Enter) — requires `allow-add-new`. `detail.value` is the typed text; `detail.option` is the created item when `addNewCallback` produced one."
+              },
+              {
+                "name": "ready",
+                "description": "The picker was built and painted for the first time (once per element lifetime). Fires right after the first build — synchronously during upgrade for a normal element, or when the render gate is released (`el.ready()` / removing `defer`) for a deferred one. No detail."
               }
             ]
           }
@@ -1755,6 +1830,10 @@
           "name": "--ms-icon-indeterminate",
           "description": "Dash glyph (mask) for a tri-state/partial checkbox; chains to --base-icon-indeterminate"
         },
+        {
+          "name": "--ms-icon-check-size",
+          "description": "mask-size for the checkmark/dash glyph inside the checkbox box; chains to --base-icon-check-size (default 68%, the same knob as pure-admin's .pa-checkbox)"
+        },
         {
           "name": "--ms-badge-counter-bg",
           "description": "Counter badge background"