@keenmate/web-multiselect 2.0.0-rc10 → 2.0.0-rc12

package/custom-elements.json

@@ -254,11 +254,11 @@
             },
             {
               "kind": "field",
-              "name": "isOpen",
+              "name": "#isOpen",
+              "privacy": "private",
               "type": {
                 "text": "boolean"
               },
-              "privacy": "private",
               "default": "false"
             },
             {
@@ -738,6 +738,14 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "inputWrapper",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "dropdown",
@@ -770,6 +778,14 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "clearButton",
+              "type": {
+                "text": "HTMLButtonElement"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "hint",
@@ -804,6 +820,15 @@
               "privacy": "private",
               "default": "null"
             },
+            {
+              "kind": "field",
+              "name": "overlayCoord",
+              "type": {
+                "text": "OverlayHandle | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
             {
               "kind": "method",
               "name": "extractField",
@@ -823,11 +848,11 @@
                 {
                   "name": "opts",
                   "type": {
-                    "text": "{\r\n        member?: string;\r\n        callback?: (item: T) => R;\r\n        tupleIndex?: 0 | 1;\r\n        tupleSkip?: boolean;\r\n        transform?: (raw: any) => R;\r\n        fallback: R | (() => R);\r\n    }"
+                    "text": "{\n        member?: string;\n        callback?: (item: T) => R;\n        tupleIndex?: 0 | 1;\n        tupleSkip?: boolean;\n        transform?: (raw: any) => R;\n        fallback: R | (() => R);\n    }"
                   }
                 }
               ],
-              "description": "Generic field extractor with the precedence:\r\n  tuple short-circuit -> member property -> callback -> fallback\r\n\r\nTuple handling:\r\n  - `tupleIndex` (0 | 1): for `[key, value]` items, return that slot.\r\n  - `tupleSkip: true`: for any tuple, skip directly to fallback (used for icon/subtitle/group/disabled —\r\n    fields that don't make sense on a 2-element array).\r\n  - neither: tuples flow through the member/callback/fallback chain as if they were objects.\r\n\r\n`transform` is applied to tuple-slot and member-property reads (not to callback returns or the fallback),\r\nso e.g. you can pass `String` to coerce numeric members to strings while letting a typed callback return its\r\nown type unchanged."
+              "description": "Generic field extractor with the precedence:\n  tuple short-circuit -> member property -> callback -> fallback\n\nTuple handling:\n  - `tupleIndex` (0 | 1): for `[key, value]` items, return that slot.\n  - `tupleSkip: true`: for any tuple, skip directly to fallback (used for icon/subtitle/group/disabled —\n    fields that don't make sense on a 2-element array).\n  - neither: tuples flow through the member/callback/fallback chain as if they were objects.\n\n`transform` is applied to tuple-slot and member-property reads (not to callback returns or the fallback),\nso e.g. you can pass `String` to coerce numeric members to strings while letting a typed callback return its\nown type unchanged."
             },
             {
               "kind": "method",
@@ -882,7 +907,7 @@
                   }
                 }
               ],
-              "description": "Badge display falls back to the regular display value rather than '[N/A]', so consumers can override badge\r\ntext independently. Doesn't fit the extractField shape (no tuple/member layer of its own)."
+              "description": "Badge display falls back to the regular display value rather than '[N/A]', so consumers can override badge\ntext independently. Doesn't fit the extractField shape (no tuple/member layer of its own)."
             },
             {
               "kind": "method",
@@ -901,7 +926,7 @@
                   }
                 }
               ],
-              "description": "Full title — a fully-qualified label supplied with the data (never computed here). Used by\r\nbadges when `isBadgeFullTitleShown` is on. Returns undefined when the option has none."
+              "description": "Full title — a fully-qualified label supplied with the data (never computed here). Used by\nbadges when `isBadgeFullTitleShown` is on. Returns undefined when the option has none."
             },
             {
               "kind": "method",
@@ -1010,7 +1035,7 @@
                   }
                 }
               ],
-              "description": "Tree mode: whether the visible node at `index` may be selected. Non-selectable\r\nnodes (see `isSelectableMember`/`getIsSelectableCallback`) still render — just\r\nwithout a checkbox — but are skipped by focus and cannot be toggled. Always\r\ntrue outside tree mode. `treeNodes` is index-aligned with `filteredOptions`."
+              "description": "Tree mode: whether the visible node at `index` may be selected. Non-selectable\nnodes (see `isSelectableMember`/`getIsSelectableCallback`) still render — just\nwithout a checkbox — but are skipped by focus and cannot be toggled. Always\ntrue outside tree mode. `treeNodes` is index-aligned with `filteredOptions`."
             },
             {
               "kind": "method",
@@ -1082,7 +1107,7 @@
                   "text": "boolean"
                 }
               },
-              "description": "Whether cascade checkbox mode is active: a multi-select tree with\r\n`checkbox-mode=\"cascade\"`. Checking a node then toggles its whole subtree\r\nand branches show a tristate box."
+              "description": "Whether cascade checkbox mode is active: a multi-select tree with\n`checkbox-mode=\"cascade\"`. Checking a node then toggles its whole subtree\nand branches show a tristate box."
             },
             {
               "kind": "method",
@@ -1122,7 +1147,7 @@
                   }
                 }
               ],
-              "description": "Toggle a tree node in cascade mode: flip its whole subtree, re-project the\r\nchecked atoms to emitted values under the active policy, and commit the diff\r\nso badges / form / change events reflect the policy (rolled-up branches, etc.)."
+              "description": "Toggle a tree node in cascade mode: flip its whole subtree, re-project the\nchecked atoms to emitted values under the active policy, and commit the diff\nso badges / form / change events reflect the policy (rolled-up branches, etc.)."
             },
             {
               "kind": "method",
@@ -1141,7 +1166,7 @@
                   }
                 }
               ],
-              "description": "Given a checked-atom set, project it to emitted values under the active\r\npolicy, diff it against the current selection, and commit. Shared by every\r\ncascade entry point (node toggle, Select All) so they all emit the same\r\npolicy-projected shape (e.g. a full subtree rolls up to one value)."
+              "description": "Given a checked-atom set, project it to emitted values under the active\npolicy, diff it against the current selection, and commit. Shared by every\ncascade entry point (node toggle, Select All) so they all emit the same\npolicy-projected shape (e.g. a full subtree rolls up to one value)."
             },
             {
               "kind": "method",
@@ -1152,7 +1177,7 @@
                   "text": "T[]"
                 }
               },
-              "description": "The \"meaningful selection\" list used by the counter chip — the rolled-up\r\nminimal cover, regardless of the active emit policy. In cascade mode\r\n`leaves`/`all` emit many values for a single branch pick, which made the\r\ncounter read e.g. `[5]` for what a person experiences as two selections.\r\nThe counter should count the branches actually chosen, and stay stable when\r\nthe policy knob flips. Outside cascade this is just the selected options."
+              "description": "The \"meaningful selection\" list used by the counter chip — the rolled-up\nminimal cover, regardless of the active emit policy. In cascade mode\n`leaves`/`all` emit many values for a single branch pick, which made the\ncounter read e.g. `[5]` for what a person experiences as two selections.\nThe counter should count the branches actually chosen, and stay stable when\nthe policy knob flips. Outside cascade this is just the selected options."
             },
             {
               "kind": "method",
@@ -1182,7 +1207,7 @@
                   "text": "void"
                 }
               },
-              "description": "Derive `treeNodes` + `filteredOptions` from the full tree, applying the\r\ncurrent search term. Matching nodes keep all their ancestors visible so\r\nindentation stays coherent (the tree is always fully expanded)."
+              "description": "Derive `treeNodes` + `filteredOptions` from the full tree, applying the\ncurrent search term. Matching nodes keep all their ancestors visible so\nindentation stays coherent (the tree is always fully expanded)."
             },
             {
               "kind": "method",
@@ -1193,7 +1218,7 @@
                   "text": "void"
                 }
               },
-              "description": "Reset the visible list to \"everything\". **Tree-aware**: in tree mode it\r\nrebuilds `treeNodes` (kept index-aligned with `filteredOptions`) from the\r\nfull tree, so the two never drift. A raw `filteredOptions = [...allOptions]`\r\nwould leave `treeNodes` stale after clearing a search — the virtual list\r\nthen reserves height for every option but renders blank rows because\r\n`treeNodes[index]` is undefined. Always use this to clear the visible list."
+              "description": "Reset the visible list to \"everything\". **Tree-aware**: in tree mode it\nrebuilds `treeNodes` (kept index-aligned with `filteredOptions`) from the\nfull tree, so the two never drift. A raw `filteredOptions = [...allOptions]`\nwould leave `treeNodes` stale after clearing a search — the virtual list\nthen reserves height for every option but renders blank rows because\n`treeNodes[index]` is undefined. Always use this to clear the visible list."
             },
             {
               "kind": "method",
@@ -1212,7 +1237,7 @@
                   }
                 }
               ],
-              "description": "Tree mode: derive the visible list from an **external** set of matched\r\noptions — e.g. the results returned by `searchCallback` — keeping each\r\nmatch's ancestors so indentation stays coherent. This is the async-search\r\nanalogue of `rebuildTreeVisible`: the matching is done by the caller (their\r\nown index/engine) instead of a local substring test, but ancestor\r\npreservation and `treeNodes`/`filteredOptions` index-alignment still happen\r\nhere. Pass all options to show the whole tree."
+              "description": "Tree mode: derive the visible list from an **external** set of matched\noptions — e.g. the results returned by `searchCallback` — keeping each\nmatch's ancestors so indentation stays coherent. This is the async-search\nanalogue of `rebuildTreeVisible`: the matching is done by the caller (their\nown index/engine) instead of a local substring test, but ancestor\npreservation and `treeNodes`/`filteredOptions` index-alignment still happen\nhere. Pass all options to show the whole tree."
             },
             {
               "kind": "method",
@@ -1223,7 +1248,7 @@
                   "text": "number"
                 }
               },
-              "description": "Tree + `search-mode=\"navigate\"`: keep the ENTIRE tree visible (the tree is always\r\nfully expanded, so `flatNodes` is the whole thing) and record which visible rows\r\nmatch the term in `matchingIndices` — the flat-list navigate behavior, but over\r\n`treeNodes`. Filter mode collapses the hierarchy to matches + ancestors; navigate\r\nmode instead leaves the structure intact so the user can jump between matches\r\n(Ctrl+Arrow on desktop, the fullscreen navigator on touch). Returns the index of\r\nthe first match, or -1 (no term / no matches), so the caller can set focus."
+              "description": "Tree + `search-mode=\"navigate\"`: keep the ENTIRE tree visible (the tree is always\nfully expanded, so `flatNodes` is the whole thing) and record which visible rows\nmatch the term in `matchingIndices` — the flat-list navigate behavior, but over\n`treeNodes`. Filter mode collapses the hierarchy to matches + ancestors; navigate\nmode instead leaves the structure intact so the user can jump between matches\n(Ctrl+Arrow on desktop, the fullscreen navigator on touch). Returns the index of\nthe first match, or -1 (no term / no matches), so the caller can set focus."
             },
             {
               "kind": "method",
@@ -1234,7 +1259,7 @@
                   "text": "void"
                 }
               },
-              "description": "(Re)compute `isRTL` from the host's `dir` (or an RTL ancestor) and derive the\r\ndirection-mirrored badges position. Pure state — callers apply the DOM effects\r\n(class toggle, panel `dir`, badge re-render). In Shadow DOM the `dir` lives on\r\nthe host element, not the shadow content, so we resolve the host first."
+              "description": "(Re)compute `isRTL` from the host's `dir` (or an RTL ancestor) and derive the\ndirection-mirrored badges position. Pure state — callers apply the DOM effects\n(class toggle, panel `dir`, badge re-render). In Shadow DOM the `dir` lives on\nthe host element, not the shadow content, so we resolve the host first."
             },
             {
               "kind": "method",
@@ -1245,7 +1270,7 @@
                   "text": "void"
                 }
               },
-              "description": "Re-read `dir` and re-apply RTL mirroring live. The web-component calls this when\r\nits `dir` attribute changes at runtime (e.g. an app-wide language/direction\r\nswitch). Most layout follows the inherited CSS `direction` automatically (the\r\ncomponent is authored with logical properties); this fixes the parts pinned at\r\nbuild time — the `.ms--rtl` class (badges/count-display placement) and the\r\nexplicit `dir` on the shadow-root-appended panels (which don't sit under the\r\n`.ms--rtl` element, so they'd otherwise keep a stale build-time direction)."
+              "description": "Re-read `dir` and re-apply RTL mirroring live. The web-component calls this when\nits `dir` attribute changes at runtime (e.g. an app-wide language/direction\nswitch). Most layout follows the inherited CSS `direction` automatically (the\ncomponent is authored with logical properties); this fixes the parts pinned at\nbuild time — the `.ms--rtl` class (badges/count-display placement) and the\nexplicit `dir` on the shadow-root-appended panels (which don't sit under the\n`.ms--rtl` element, so they'd otherwise keep a stale build-time direction)."
             },
             {
               "kind": "method",
@@ -1307,7 +1332,7 @@
                   "text": "void"
                 }
               },
-              "description": "Round the OUTER corners of the row at the very top and the row at the very\r\nbottom of the list so a focused/selected row's background — and crucially its\r\nfocus `outline`, which traces the row's OWN box and follows its border-radius\r\nbut NOT an ancestor's overflow clip — curves with the panel instead of poking a\r\nsquare corner past it.\r\n\r\nKeyed off DOM order, not option index, so grouping works: when grouped the top\r\nrow is a `.ms__group-label` (not the first option, which sits below it), so we\r\nround whichever element is physically first/last. VirtualScroll renders rows in\r\nindex order into one innerHTML, so DOM order == visual order there too.\r\n\r\nLogical corners (`border-start-*` / `border-end-*`) so it mirrors in RTL. A\r\nspace-taking vertical scrollbar occupies the inline-END gutter, so the END-side\r\ncorners stay square then (the panel's rounded end corner is the scrollbar\r\ntrack's). The radius is 0 in the fullscreen sheet (that scope zeroes the var)."
+              "description": "Round the OUTER corners of the row at the very top and the row at the very\nbottom of the list so a focused/selected row's background — and crucially its\nfocus `outline`, which traces the row's OWN box and follows its border-radius\nbut NOT an ancestor's overflow clip — curves with the panel instead of poking a\nsquare corner past it.\n\nKeyed off DOM order, not option index, so grouping works: when grouped the top\nrow is a `.ms__group-label` (not the first option, which sits below it), so we\nround whichever element is physically first/last. VirtualScroll renders rows in\nindex order into one innerHTML, so DOM order == visual order there too.\n\nLogical corners (`border-start-*` / `border-end-*`) so it mirrors in RTL. A\nspace-taking vertical scrollbar occupies the inline-END gutter, so the END-side\ncorners stay square then (the panel's rounded end corner is the scrollbar\ntrack's). The radius is 0 in the fullscreen sheet (that scope zeroes the var)."
             },
             {
               "kind": "method",
@@ -1337,7 +1362,7 @@
                   }
                 }
               ],
-              "description": "Default enabled/disabled state for the built-in actions, applied only when the consumer hasn't\r\nset an explicit `isDisabled` / `getIsDisabledCallback`:\r\n- `select-all` is disabled when it would add nothing (every selectable, non-disabled filtered\r\n  option is already selected — this also covers an empty list).\r\n- `clear-all` is disabled when nothing is selected."
+              "description": "Default enabled/disabled state for the built-in actions, applied only when the consumer hasn't\nset an explicit `isDisabled` / `getIsDisabledCallback`:\n- `select-all` is disabled when it would add nothing (every selectable, non-disabled filtered\n  option is already selected — this also covers an empty list).\n- `clear-all` is disabled when nothing is selected."
             },
             {
               "kind": "method",
@@ -1382,7 +1407,7 @@
                   "text": "string"
                 }
               },
-              "description": "Trailing info affordance for an option row, emitted only for the fullscreen\r\noverlay. CSS keeps it hidden until `markTruncatedOptions()` tags the row\r\n`.ms__option--truncated`, so it appears only when the label is actually clipped.\r\nTapping it reveals the full label — the touch substitute for the hover option\r\ntooltip, which never fires on touch (the very devices that get fullscreen).\r\n`tabindex=\"-1\"` keeps it out of the tab order; the search input owns keyboarding."
+              "description": "Trailing info affordance for an option row, emitted only for the fullscreen\noverlay. CSS keeps it hidden until `markTruncatedOptions()` tags the row\n`.ms__option--truncated`, so it appears only when the label is actually clipped.\nTapping it reveals the full label — the touch substitute for the hover option\ntooltip, which never fires on touch (the very devices that get fullscreen).\n`tabindex=\"-1\"` keeps it out of the tab order; the search input owns keyboarding."
             },
             {
               "kind": "method",
@@ -1407,7 +1432,7 @@
                   }
                 }
               ],
-              "description": "Render a single tree-mode row. Separate from `renderOption`: a tree row is\r\nindented by its depth (via the `--ms-tree-depth` custom property) and\r\ntagged branch/leaf, but otherwise carries the same selection/checkbox/\r\nicon/subtitle content. The tree is always fully expanded, so there is no\r\nchevron/toggle — every node is just a normal, selectable option."
+              "description": "Render a single tree-mode row. Separate from `renderOption`: a tree row is\nindented by its depth (via the `--ms-tree-depth` custom property) and\ntagged branch/leaf, but otherwise carries the same selection/checkbox/\nicon/subtitle content. The tree is always fully expanded, so there is no\nchevron/toggle — every node is just a normal, selectable option."
             },
             {
               "kind": "method",
@@ -1470,7 +1495,7 @@
                   "text": "string"
                 }
               },
-              "description": "Resolve the closed-state input placeholder for the current data/search state.\r\nPriority: explicit no-data placeholder (when the list is empty) → \"pick\" prompt when\r\nsearch is unusable → the search placeholder."
+              "description": "Resolve the closed-state input placeholder for the current data/search state.\nPriority: explicit no-data placeholder (when the list is empty) → \"pick\" prompt when\nsearch is unusable → the search placeholder."
             },
             {
               "kind": "method",
@@ -1481,7 +1506,7 @@
                   "text": "string"
                 }
               },
-              "description": "The search field placeholder. An explicit `searchPlaceholder` always wins and stays\r\nfixed. Otherwise the default is \"Search...\" — except when the in-overlay mode toggle\r\nis enabled (`isSearchModeToggleShown`), where it becomes mode-aware so the field labels\r\nthe current behavior: \"Search…\" in navigate mode, \"Filter…\" in filter mode. Refreshed\r\non a live mode switch (see setSearchModeLive → refreshSearchPlaceholder)."
+              "description": "The search field placeholder. An explicit `searchPlaceholder` always wins and stays\nfixed. Otherwise the default is \"Search...\" — except when the in-overlay mode toggle\nis enabled (`isSearchModeToggleShown`), where it becomes mode-aware so the field labels\nthe current behavior: \"Search…\" in navigate mode, \"Filter…\" in filter mode. Refreshed\non a live mode switch (see setSearchModeLive → refreshSearchPlaceholder)."
             },
             {
               "kind": "method",
@@ -1541,7 +1566,7 @@
                   "text": "void"
                 }
               },
-              "description": "Abort the search request currently in flight, if any. The aborted request's results\r\nare then ignored (and the consumer's `searchCallback` can short-circuit its fetch via\r\nthe `AbortSignal` it was handed)."
+              "description": "Abort the search request currently in flight, if any. The aborted request's results\nare then ignored (and the consumer's `searchCallback` can short-circuit its fetch via\nthe `AbortSignal` it was handed)."
             },
             {
               "kind": "method",
@@ -1566,7 +1591,7 @@
                   }
                 }
               ],
-              "description": "Invoke the async `searchCallback` and apply its results. Split out of `handleSearch`\r\nso it can be called immediately or after the debounce timer.\r\n\r\nAny request still in flight is aborted before a new one starts, so a slow earlier\r\nrequest can't overwrite a newer one — and consumers that wire the passed `AbortSignal`\r\ninto their fetch get the request actually cancelled, not just ignored. The\r\n`aborted` / `searchTerm === value` guards drop superseded or out-of-order responses."
+              "description": "Invoke the async `searchCallback` and apply its results. Split out of `handleSearch`\nso it can be called immediately or after the debounce timer.\n\nAny request still in flight is aborted before a new one starts, so a slow earlier\nrequest can't overwrite a newer one — and consumers that wire the passed `AbortSignal`\ninto their fetch get the request actually cancelled, not just ignored. The\n`aborted` / `searchTerm === value` guards drop superseded or out-of-order responses."
             },
             {
               "kind": "method",
@@ -1664,7 +1689,7 @@
                   }
                 }
               ],
-              "description": "Move focus by computing a new index from (current, total).\r\nReturning -1 from `compute` is a no-op (used for empty list / no match)."
+              "description": "Move focus by computing a new index from (current, total).\nReturning -1 from `compute` is a no-op (used for empty list / no match)."
             },
             {
               "kind": "method",
@@ -1695,7 +1720,7 @@
                   }
                 }
               ],
-              "description": "Given a target index and a preferred direction, return the nearest index\r\nwhose node is selectable (skipping non-selectable tree nodes). Falls back to\r\nthe opposite direction, then to -1 if nothing is selectable. No-op outside\r\ntree mode."
+              "description": "Given a target index and a preferred direction, return the nearest index\nwhose node is selectable (skipping non-selectable tree nodes). Falls back to\nthe opposite direction, then to -1 if nothing is selectable. No-op outside\ntree mode."
             },
             {
               "kind": "method",
@@ -1786,7 +1811,7 @@
                   "text": "MultiSelectKeyboardController<T>"
                 }
               },
-              "description": "Lazily build (and cache) the imperative facade passed to `keydownCallback`. Bound to the\r\nsame private actions the built-in key handling uses, so consumer shortcuts behave identically."
+              "description": "Lazily build (and cache) the imperative facade passed to `keydownCallback`. Bound to the\nsame private actions the built-in key handling uses, so consumer shortcuts behave identically."
             },
             {
               "kind": "method",
@@ -1797,7 +1822,7 @@
                   "text": "void"
                 }
               },
-              "description": "Clear the search box (both the main input and the fullscreen search) and reset the visible\r\nlist. Shared by Escape and the keyboard controller."
+              "description": "Clear the search box (both the main input and the fullscreen search) and reset the visible\nlist. Shared by Escape and the keyboard controller."
             },
             {
               "kind": "method",
@@ -1844,7 +1869,7 @@
                   }
                 }
               ],
-              "description": "The single funnel for an interactive (user-initiated) selection. Consults\r\n`beforeSelectCallback` and only mutates state if allowed, so the veto can\r\nnever be bypassed by a new UI entry point. Programmatic `setSelected` and\r\nthe Select-All button deliberately do not route through here.\r\nReturns true if the option was selected, false if the veto blocked it."
+              "description": "The single funnel for an interactive (user-initiated) selection. Consults\n`beforeSelectCallback` and only mutates state if allowed, so the veto can\nnever be bypassed by a new UI entry point. Programmatic `setSelected` and\nthe Select-All button deliberately do not route through here.\nReturns true if the option was selected, false if the veto blocked it."
             },
             {
               "kind": "method",
@@ -1863,7 +1888,7 @@
                   }
                 }
               ],
-              "description": "The single funnel for an interactive (user-initiated) deselection. Every\r\nremoval affordance — dropdown toggle, badge × button, selected-items\r\npopover × button, and the \"remove hidden\" badge — routes through here so\r\nthe `beforeDeselectCallback` veto applies uniformly. Programmatic\r\n`setSelected` and the Clear-All button deliberately bypass it.\r\nReturns true if the option was deselected, false if the veto blocked it."
+              "description": "The single funnel for an interactive (user-initiated) deselection. Every\nremoval affordance — dropdown toggle, badge × button, selected-items\npopover × button, and the \"remove hidden\" badge — routes through here so\nthe `beforeDeselectCallback` veto applies uniformly. Programmatic\n`setSelected` and the Clear-All button deliberately bypass it.\nReturns true if the option was deselected, false if the veto blocked it."
             },
             {
               "kind": "method",
@@ -1939,6 +1964,28 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "clearClick",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Inline clear (✕) handler: wipe the whole selection and any search text, then\nrestore focus to the input. clearAll() → commit() → renderBadges() already\nrefreshes this button's visibility (it hides once nothing is selected)."
+            },
+            {
+              "kind": "method",
+              "name": "updateClearButton",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Show the inline clear (✕) only when it is opted in (isClearShown), something is\nselected, and the control is enabled. Called from renderBadges() so it tracks\nevery selection change. Uses inline display like the counter / fullscreen clear."
+            },
             {
               "kind": "method",
               "name": "commit",
@@ -1956,27 +2003,45 @@
                   }
                 }
               ],
-              "description": "Re-render and fire callbacks after a selection state change.\r\n`added` / `removed` drive per-item select/deselect callbacks.\r\n`onChange` fires once if anything actually changed."
+              "description": "Re-render and fire callbacks after a selection state change.\n`added` / `removed` drive per-item select/deselect callbacks.\n`onChange` fires once if anything actually changed."
             },
             {
               "kind": "method",
               "name": "open",
-              "privacy": "private",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              }
+              },
+              "description": "Open the dropdown (no-op if already open, or if there is nothing to show)."
             },
             {
               "kind": "method",
               "name": "close",
-              "privacy": "private",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              }
+              },
+              "description": "Close the dropdown (no-op if already closed)."
+            },
+            {
+              "kind": "method",
+              "name": "toggle",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Toggle the dropdown open/closed."
+            },
+            {
+              "kind": "field",
+              "name": "isOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the dropdown is currently open. Assigning opens/closes it."
             },
             {
               "kind": "method",
@@ -1997,11 +2062,11 @@
                 {
                   "name": "opts",
                   "type": {
-                    "text": "{\r\n        getPlacement: () => Placement | null;\r\n        setPlacement: (p: Placement) => void;\r\n        /** When false, never locks (re-flips on every update). Defaults to true. */\r\n        isLocked?: () => boolean;\r\n        applyMaxWidth?: boolean;\r\n        afterPosition?: () => void;\r\n    }"
+                    "text": "{\n        getPlacement: () => Placement | null;\n        setPlacement: (p: Placement) => void;\n        /** When false, never locks (re-flips on every update). Defaults to true. */\n        isLocked?: () => boolean;\n        applyMaxWidth?: boolean;\n        afterPosition?: () => void;\n    }"
                   }
                 }
               ],
-              "description": "Anchor a floating panel (dropdown or selected-items popover) below/above the input with\r\nplacement-locking and width-syncing. Returns the `autoUpdate` cleanup.\r\n\r\nBoth panels share: anchor on input, sync width, default to 'bottom-start', flip on first\r\ncompute then lock the resulting placement, optionally clamp by dropdownMin/MaxWidth."
+              "description": "Anchor a floating panel (dropdown or selected-items popover) below/above the input with\nplacement-locking and width-syncing. Returns the `autoUpdate` cleanup.\n\nBoth panels share: anchor on input, sync width, default to 'bottom-start', flip on first\ncompute then lock the resulting placement, optionally clamp by dropdownMin/MaxWidth."
             },
             {
               "kind": "method",
@@ -2020,7 +2085,7 @@
                   }
                 }
               ],
-              "description": "Surface a multiselect-branded, once-per-instance warning when core's drift check\r\n(`anchor`'s `onDrift`) reports the panel didn't land where it was positioned. The\r\nconsumer has an ancestor that establishes a fixed containing block but isn't on the\r\nreliable-anchors list (likely `contain: paint|layout|strict` or `container-type`).\r\nWe can't fix it from inside the library, but we point at the likely culprit. Core\r\nowns the measurement + culprit-finding + CB-CSS diagnostic (`detectFixedDrift`)."
+              "description": "Surface a multiselect-branded, once-per-instance warning when core's drift check\n(`anchor`'s `onDrift`) reports the panel didn't land where it was positioned. The\nconsumer has an ancestor that establishes a fixed containing block but isn't on the\nreliable-anchors list (likely `contain: paint|layout|strict` or `container-type`).\nWe can't fix it from inside the library, but we point at the likely culprit. Core\nowns the measurement + culprit-finding + CB-CSS diagnostic (`detectFixedDrift`)."
             },
             {
               "kind": "method",
@@ -2031,7 +2096,7 @@
                   "text": "void"
                 }
               },
-              "description": "Fullscreen counterpart of warnDrift. The overlay is a `position: fixed`,\r\nfull-viewport sheet — but if an ancestor of the host establishes a fixed-positioning\r\ncontaining block (`transform` / `perspective` / `filter` / `backdrop-filter` / a\r\nqualifying `will-change`), the browser anchors the sheet to THAT ancestor's box instead\r\nof the viewport, so it no longer covers the screen (offset, clipped, or mis-sized).\r\n\r\nUnlike the floating path — where core measures real drift after positioning — nothing\r\nanchors the sheet, so there's no drift to observe. Instead we ask core's shared\r\nheuristic (`getFixedPositionOffsetParent`, the same one that feeds the floating platform)\r\nwhether the sheet's true offset parent is the viewport (`window`) or an element. An\r\nelement means it WILL be mis-anchored; warn once, pointing at the culprit. We only check\r\nthe reliably-honoured properties core lists (transform family) — `contain` /\r\n`container-type` are omitted because browsers don't honour them for fixed positioning,\r\nso they don't actually break the sheet."
+              "description": "Fullscreen counterpart of warnDrift. The overlay is a `position: fixed`,\nfull-viewport sheet — but if an ancestor of the host establishes a fixed-positioning\ncontaining block (`transform` / `perspective` / `filter` / `backdrop-filter` / a\nqualifying `will-change`), the browser anchors the sheet to THAT ancestor's box instead\nof the viewport, so it no longer covers the screen (offset, clipped, or mis-sized).\n\nUnlike the floating path — where core measures real drift after positioning — nothing\nanchors the sheet, so there's no drift to observe. Instead we ask core's shared\nheuristic (`getFixedPositionOffsetParent`, the same one that feeds the floating platform)\nwhether the sheet's true offset parent is the viewport (`window`) or an element. An\nelement means it WILL be mis-anchored; warn once, pointing at the culprit. We only check\nthe reliably-honoured properties core lists (transform family) — `contain` /\n`container-type` are omitted because browsers don't honour them for fixed positioning,\nso they don't actually break the sheet."
             },
             {
               "kind": "method",
@@ -2060,7 +2125,7 @@
                   }
                 }
               ],
-              "description": "Switch how the open panels are presented. 'floating' anchors them to the input\r\n(the default); 'fullscreen' renders them as full-viewport overlays (the phone\r\npattern) — the dropdown with its own search header + close, the selected-items\r\npopover with its existing header + close. Driven by the element's\r\n`environmentChanged` hook (auto → fullscreen on phones). A no-op when unchanged;\r\nwhen a panel is already open it re-applies live so an orientation flip / viewport\r\nresize can swap presentation without a reopen."
+              "description": "Switch how the open panels are presented. 'floating' anchors them to the input\n(the default); 'fullscreen' renders them as full-viewport overlays (the phone\npattern) — the dropdown with its own search header + close, the selected-items\npopover with its existing header + close. Driven by the element's\n`environmentChanged` hook (auto → fullscreen on phones). A no-op when unchanged;\nwhen a panel is already open it re-applies live so an orientation flip / viewport\nresize can swap presentation without a reopen."
             },
             {
               "kind": "method",
@@ -2071,7 +2136,7 @@
                   "text": "void"
                 }
               },
-              "description": "Lock page scroll behind a fullscreen overlay via the core ref-counted helper.\r\nIdempotent per instance: the dropdown and the selected-items popover are mutually\r\nexclusive (opening one closes the other), so we hold at most one lock at a time,\r\nand a redundant call is a no-op rather than acquiring a second."
+              "description": "Lock page scroll behind a fullscreen overlay via the core ref-counted helper.\nIdempotent per instance: the dropdown and the selected-items popover are mutually\nexclusive (opening one closes the other), so we hold at most one lock at a time,\nand a redundant call is a no-op rather than acquiring a second."
             },
             {
               "kind": "method",
@@ -2093,7 +2158,7 @@
                   "text": "void"
                 }
               },
-              "description": "Clip the host document's horizontal overflow while a fullscreen sheet is open.\r\n\r\nA page that overflows horizontally (e.g. an unbreakable-wide token in a heading)\r\nmakes the mobile browser SHRINK-TO-FIT: it zooms the page out so the overflow fits,\r\nwhich desyncs the visual viewport from the layout viewport. Our fullscreen sheet is\r\n`position: fixed` — anchored to the LAYOUT viewport — so under that zoom it no longer\r\nlands flush against the physical screen edges, and the top slips under the system bar\r\n(looks like \"the bar covers the sheet\"). This is NOT a safe-area problem; safe-area\r\ninsets are 0 in that state. Clamping `overflow-x: hidden` on <html>/<body> removes the\r\noverflow, so the browser drops the zoom and the sheet sits flush. Complements\r\nlockBodyScroll() (vertical axis); the saved inline value is restored on close.\r\n\r\nOnly <html> is touched (not <body>): clipping the root's horizontal overflow is\r\nenough to collapse the scrollWidth and cancel the shrink-to-fit, and it avoids\r\nconflicting with core's lockBodyScroll(), which owns <body>'s `overflow`. Idempotent."
+              "description": "Clip the host document's horizontal overflow while a fullscreen sheet is open.\n\nA page that overflows horizontally (e.g. an unbreakable-wide token in a heading)\nmakes the mobile browser SHRINK-TO-FIT: it zooms the page out so the overflow fits,\nwhich desyncs the visual viewport from the layout viewport. Our fullscreen sheet is\n`position: fixed` — anchored to the LAYOUT viewport — so under that zoom it no longer\nlands flush against the physical screen edges, and the top slips under the system bar\n(looks like \"the bar covers the sheet\"). This is NOT a safe-area problem; safe-area\ninsets are 0 in that state. Clamping `overflow-x: hidden` on <html>/<body> removes the\noverflow, so the browser drops the zoom and the sheet sits flush. Complements\nlockBodyScroll() (vertical axis); the saved inline value is restored on close.\n\nOnly <html> is touched (not <body>): clipping the root's horizontal overflow is\nenough to collapse the scrollWidth and cancel the shrink-to-fit, and it avoids\nconflicting with core's lockBodyScroll(), which owns <body>'s `overflow`. Idempotent."
             },
             {
               "kind": "method",
@@ -2115,7 +2180,7 @@
                   "text": "void"
                 }
               },
-              "description": "While the fullscreen dropdown is open, keep it sitting above the soft keyboard.\r\nDelegates to core's `observeKeyboardInset` (which tracks `window.visualViewport`\r\nand pins the panel's height/top so its flex column reflows above the keyboard);\r\nwe just hold the returned cleanup. No-op where `visualViewport` is unavailable."
+              "description": "While the fullscreen dropdown is open, keep it sitting above the soft keyboard.\nDelegates to core's `observeKeyboardInset` (which tracks `window.visualViewport`\nand pins the panel's height/top so its flex column reflows above the keyboard);\nwe just hold the returned cleanup. No-op where `visualViewport` is unavailable."
             },
             {
               "kind": "method",
@@ -2137,7 +2202,7 @@
                   "text": "number"
                 }
               },
-              "description": "The fullscreen size multiplier = `--ms-fullscreen-rem ÷ --ms-rem` (both read off\r\nthe host). CSS scales itself — every size is `calc(N × --ms-rem)` and the panel\r\noverrides `--ms-rem` — so this exists only for the JS-driven pixel heights that\r\nCSS can't reach: the virtual/fixed option rows and the popover's virtual badges.\r\nReturns 1 when floating (or when computed styles aren't readable, e.g. jsdom)."
+              "description": "The fullscreen size multiplier = `--ms-fullscreen-rem ÷ --ms-rem` (both read off\nthe host). CSS scales itself — every size is `calc(N × --ms-rem)` and the panel\noverrides `--ms-rem` — so this exists only for the JS-driven pixel heights that\nCSS can't reach: the virtual/fixed option rows and the popover's virtual badges.\nReturns 1 when floating (or when computed styles aren't readable, e.g. jsdom)."
             },
             {
               "kind": "method",
@@ -2167,7 +2232,7 @@
                   }
                 }
               ],
-              "description": "Size the virtual options scroll container for the current presentation. Applied on\r\nevery render (the container itself is built once), so a floating⇄fullscreen switch\r\nre-sizes it: floating = a fixed maxHeight scroll box; fullscreen = flex-fill the\r\npanel's flex column (no fixed height). Also refreshes --ms-option-height to the\r\nscaled row height so the CSS row height matches the virtual scroller's itemHeight."
+              "description": "Size the virtual options scroll container for the current presentation. Applied on\nevery render (the container itself is built once), so a floating⇄fullscreen switch\nre-sizes it: floating = a fixed maxHeight scroll box; fullscreen = flex-fill the\npanel's flex column (no fixed height). Also refreshes --ms-option-height to the\nscaled row height so the CSS row height matches the virtual scroller's itemHeight."
             },
             {
               "kind": "method",
@@ -2178,7 +2243,7 @@
                   "text": "number"
                 }
               },
-              "description": "Virtual popover badge row height (px). In the fullscreen phone view the rows are\r\nscaled up AND given extra height so a selected item is a comfortable, dropdown-like\r\ntouch target (the default 36px pill is short for touch). Mirrors the CSS\r\n`--ms-badge-height` override for the fullscreen popover (floating.css) so the\r\nvirtual list's fixed height agrees with the non-virtual pills."
+              "description": "Virtual popover badge row height (px). In the fullscreen phone view the rows are\nscaled up AND given extra height so a selected item is a comfortable, dropdown-like\ntouch target (the default 36px pill is short for touch). Mirrors the CSS\n`--ms-badge-height` override for the fullscreen popover (floating.css) so the\nvirtual list's fixed height agrees with the non-virtual pills."
             },
             {
               "kind": "method",
@@ -2197,7 +2262,7 @@
                   }
                 }
               ],
-              "description": "Clear the inline geometry that floating-ui's `anchor` writes on a panel\r\n(position/left/top plus our composed max-width/min-width). Inline styles beat\r\nthe stylesheet, so a panel left over from a floating cycle would otherwise pin\r\nitself where it last anchored and ignore the fullscreen CSS (position: fixed;\r\ninset: 0; width: 100vw). Must run when switching a panel floating → fullscreen."
+              "description": "Clear the inline geometry that floating-ui's `anchor` writes on a panel\n(position/left/top plus our composed max-width/min-width). Inline styles beat\nthe stylesheet, so a panel left over from a floating cycle would otherwise pin\nitself where it last anchored and ignore the fullscreen CSS (position: fixed;\ninset: 0; width: 100vw). Must run when switching a panel floating → fullscreen."
             },
             {
               "kind": "method",
@@ -2230,7 +2295,7 @@
                   "text": "void"
                 }
               },
-              "description": "Back-gesture handling for the fullscreen sheet. On open we push a history entry\r\n(same URL) and listen for `popstate`; the phone Back gesture/button then pops that\r\nentry — which we treat as \"close the sheet\" — instead of navigating away from the\r\npage. A programmatic close (✕, selection, Escape) consumes the entry via\r\n`history.back()` so the stack is left as it was found."
+              "description": "Back-gesture handling for the fullscreen sheet. On open we push a history entry\n(same URL) and listen for `popstate`; the phone Back gesture/button then pops that\nentry — which we treat as \"close the sheet\" — instead of navigating away from the\npage. A programmatic close (✕, selection, Escape) consumes the entry via\n`history.back()` so the stack is left as it was found."
             },
             {
               "kind": "method",
@@ -2241,7 +2306,7 @@
                   "text": "void"
                 }
               },
-              "description": "Back gesture/button fired: our pushed entry is already gone, so just close the\r\nsheet — WITHOUT popping history again (popOverlayHistory becomes a no-op)."
+              "description": "Back gesture/button fired: our pushed entry is already gone, so just close the\nsheet — WITHOUT popping history again (popOverlayHistory becomes a no-op)."
             },
             {
               "kind": "method",
@@ -2252,7 +2317,7 @@
                   "text": "void"
                 }
               },
-              "description": "Programmatic close: remove the listener and pop the entry we pushed (so the\r\nhistory stack returns to its pre-open state). No-op if a Back gesture already\r\nconsumed it (overlayHistoryActive is false by then)."
+              "description": "Programmatic close: remove the listener and pop the entry we pushed (so the\nhistory stack returns to its pre-open state). No-op if a Back gesture already\nconsumed it (overlayHistoryActive is false by then)."
             },
             {
               "kind": "method",
@@ -2263,7 +2328,7 @@
                   "text": "void"
                 }
               },
-              "description": "Build the fullscreen overlay header: a search field (proxying to the same\r\n`handleSearch`/`handleKeydown` path as the main input, since the overlay covers\r\nit) plus a close button. Inserted before the scrolling list so it pins to the\r\ntop of the fixed panel. `renderDropdown()` only rewrites `dropdownInner`, so the\r\nheader survives re-renders."
+              "description": "Build the fullscreen overlay header: a search field (proxying to the same\n`handleSearch`/`handleKeydown` path as the main input, since the overlay covers\nit) plus a close button. Inserted before the scrolling list so it pins to the\ntop of the fixed panel. `renderDropdown()` only rewrites `dropdownInner`, so the\nheader survives re-renders."
             },
             {
               "kind": "method",
@@ -2274,7 +2339,7 @@
                   "text": "void"
                 }
               },
-              "description": "Build the navigate-mode match navigator (count + prev/next) and append it to the\r\nfullscreen header, once. No-op if already built or the header isn't present. The\r\nnav wraps onto its own full-width row under the search box (header is flex-wrap;\r\nthe nav takes 100% basis)."
+              "description": "Build the navigate-mode match navigator (count + prev/next) and append it to the\nfullscreen header, once. No-op if already built or the header isn't present. The\nnav wraps onto its own full-width row under the search box (header is flex-wrap;\nthe nav takes 100% basis)."
             },
             {
               "kind": "method",
@@ -2315,7 +2380,7 @@
                   }
                 }
               ],
-              "description": "Switch searchMode in place — the overlay's toggle path. The `search-mode` attribute\r\nis reinit-on-change (it rebuilds and closes the overlay); this instead mutates the\r\nlive config, adds/removes the match navigator to match, and re-projects the current\r\nterm under the new mode (filter narrows the list / navigate keeps all + highlights),\r\nall without tearing the open sheet down. Focus stays on the search field."
+              "description": "Switch searchMode in place — the overlay's toggle path. The `search-mode` attribute\nis reinit-on-change (it rebuilds and closes the overlay); this instead mutates the\nlive config, adds/removes the match navigator to match, and re-projects the current\nterm under the new mode (filter narrows the list / navigate keeps all + highlights),\nall without tearing the open sheet down. Focus stays on the search field."
             },
             {
               "kind": "method",
@@ -2326,7 +2391,7 @@
                   "text": "void"
                 }
               },
-              "description": "Sync the mode toggle's icon (via data-mode) and labels with the current searchMode.\r\nNo-op when the toggle isn't built (opt-out, floating panel, or search hidden)."
+              "description": "Sync the mode toggle's icon (via data-mode) and labels with the current searchMode.\nNo-op when the toggle isn't built (opt-out, floating panel, or search hidden)."
             },
             {
               "kind": "method",
@@ -2337,7 +2402,7 @@
                   "text": "void"
                 }
               },
-              "description": "Sync the fullscreen match navigator (navigate mode only) with the current search\r\nstate: hide it until there's a term, then show \"N of M\" while a match is focused\r\n(or \"M matches\" / \"No matches\"), and disable the prev/next buttons when there's\r\nnothing to step through. No-op when the navigator isn't built (floating panel,\r\nfilter mode, or search disabled)."
+              "description": "Sync the fullscreen match navigator (navigate mode only) with the current search\nstate: hide it until there's a term, then show \"N of M\" while a match is focused\n(or \"M matches\" / \"No matches\"), and disable the prev/next buttons when there's\nnothing to step through. No-op when the navigator isn't built (floating panel,\nfilter mode, or search disabled)."
             },
             {
               "kind": "method",
@@ -2348,7 +2413,7 @@
                   "text": "void"
                 }
               },
-              "description": "Show the fullscreen search's inline clear (✕) only while the field has text.\r\nNo-op when the button isn't built (floating panel, readonly/hidden search)."
+              "description": "Show the fullscreen search's inline clear (✕) only while the field has text.\nNo-op when the button isn't built (floating panel, readonly/hidden search)."
             },
             {
               "kind": "method",
@@ -2359,7 +2424,7 @@
                   "text": "void"
                 }
               },
-              "description": "Clear the fullscreen search term via the same path a keystroke takes, then\r\nrefocus the field so the user can keep typing. Touch has no keyboard Escape,\r\nso this button is the on-screen way to reset a search."
+              "description": "Clear the fullscreen search term via the same path a keystroke takes, then\nrefocus the field so the user can keep typing. Touch has no keyboard Escape,\nso this button is the on-screen way to reset a search."
             },
             {
               "kind": "method",
@@ -2390,7 +2455,7 @@
                   "text": "void"
                 }
               },
-              "description": "Resolve any `selectedValues` entries that don't yet have a matching\r\n`selectedOptions` object by looking them up in the current `allOptions`.\r\nIdempotent; safe to call after init *and* after `options` is replaced\r\n(e.g., async fetch, `searchCallback` result, or late `element.options =`\r\nassignment). Without this, `initial-values` declared before options\r\narrive ends up with phantom values that `getValue()` can never report."
+              "description": "Resolve any `selectedValues` entries that don't yet have a matching\n`selectedOptions` object by looking them up in the current `allOptions`.\nIdempotent; safe to call after init *and* after `options` is replaced\n(e.g., async fetch, `searchCallback` result, or late `element.options =`\nassignment). Without this, `initial-values` declared before options\narrive ends up with phantom values that `getValue()` can never report."
             },
             {
               "kind": "method",
@@ -2473,7 +2538,7 @@
                   }
                 }
               ],
-              "description": "Coerce a render-callback result to an HTML string. Callbacks may return a string\r\n(HTML) or an HTMLElement (serialized via `outerHTML`); null/undefined → ''. Used by\r\nevery \"return string | HTMLElement\" content callback that builds into an innerHTML\r\nstring. (DOM sinks that hold a live node instead — the reveal/message panels — use\r\ntextContent/appendChild directly and intentionally don't go through here.)"
+              "description": "Coerce a render-callback result to an HTML string. Callbacks may return a string\n(HTML) or an HTMLElement (serialized via `outerHTML`); null/undefined → ''. Used by\nevery \"return string | HTMLElement\" content callback that builds into an innerHTML\nstring. (DOM sinks that hold a live node instead — the reveal/message panels — use\ntextContent/appendChild directly and intentionally don't go through here.)"
             },
             {
               "kind": "method",
@@ -2492,7 +2557,7 @@
                   }
                 }
               ],
-              "description": "Normalize a class callback result (`string | string[] | null`) to a single\r\nspace-joined string with falsy entries dropped — e.g. `['a', '', 'b'] → \"a b\"`,\r\n`null → \"\"`. Callers add their own leading space / base class as needed."
+              "description": "Normalize a class callback result (`string | string[] | null`) to a single\nspace-joined string with falsy entries dropped — e.g. `['a', '', 'b'] → \"a b\"`,\n`null → \"\"`. Callers add their own leading space / base class as needed."
             },
             {
               "kind": "method",
@@ -2517,7 +2582,7 @@
                   }
                 }
               ],
-              "description": "Render a removable badge for a selected option (used by the badges/partial display modes\r\nand by the selected-items popover).\r\n\r\n- In the popover, `renderSelectedItemContentCallback` and `getSelectedItemClassCallback` win\r\n  over the regular badge callbacks; that's how consumers customize popover items independently.\r\n- The `data-value` and aria-label both go through `getItemBadgeDisplayValue` so badge text and\r\n  accessible name stay in sync."
+              "description": "Render a removable badge for a selected option (used by the badges/partial display modes\nand by the selected-items popover).\n\n- In the popover, `renderSelectedItemContentCallback` and `getSelectedItemClassCallback` win\n  over the regular badge callbacks; that's how consumers customize popover items independently.\n- The `data-value` and aria-label both go through `getItemBadgeDisplayValue` so badge text and\n  accessible name stay in sync."
             },
             {
               "kind": "method",
@@ -2601,7 +2666,7 @@
                   }
                 }
               ],
-              "description": "Set the selection programmatically. **Silent by default** — it does not fire\r\n`select`/`deselect`/`change` (so restoring saved state, cascade resets, or a\r\nserver-authoritative correction can't loop back or trip \"user changed it\"\r\nhandlers). Pass `{ notify: true }` to announce the result as a **single\r\naggregate `change`** — for a deliberate user gesture (e.g. an action button)\r\nthat should reach the same listeners a manual pick does, without the per-item\r\n`select`/`deselect` flood a bulk change would otherwise cause."
+              "description": "Set the selection programmatically. **Silent by default** — it does not fire\n`select`/`deselect`/`change` (so restoring saved state, cascade resets, or a\nserver-authoritative correction can't loop back or trip \"user changed it\"\nhandlers). Pass `{ notify: true }` to announce the result as a **single\naggregate `change`** — for a deliberate user gesture (e.g. an action button)\nthat should reach the same listeners a manual pick does, without the per-item\n`select`/`deselect` flood a bulk change would otherwise cause."
             },
             {
               "kind": "method",
@@ -2620,7 +2685,7 @@
                   }
                 }
               ],
-              "description": "Merge a partial config update into the live picker without tearing down the DOM.\r\n\r\nHandles the cheap structural toggles inline (no-checkboxes class, badges-position class,\r\ninput placeholder, search-input mode) and re-renders dropdown + badges + hidden inputs.\r\n\r\nReturns `true` if the change could be applied in place. Returns `false` for changes that\r\ntruly require rebuilding the DOM scaffolding (currently: adding/removing the `searchHint`\r\nelement, since it's only created in `buildHTML` if a hint string was provided). The caller\r\nshould fall back to destroy + re-init in that case."
+              "description": "Merge a partial config update into the live picker without tearing down the DOM.\n\nHandles the cheap structural toggles inline (no-checkboxes class, badges-position class,\ninput placeholder, search-input mode) and re-renders dropdown + badges + hidden inputs.\n\nReturns `true` if the change could be applied in place. Returns `false` for changes that\ntruly require rebuilding the DOM scaffolding (currently: adding/removing the `searchHint`\nelement, since it's only created in `buildHTML` if a hint string was provided). The caller\nshould fall back to destroy + re-init in that case."
             },
             {
               "kind": "field",
@@ -2663,11 +2728,11 @@
                 {
                   "name": "spec",
                   "type": {
-                    "text": "{\r\n        id: string;\r\n        trigger: HTMLElement;\r\n        content: string | HTMLElement;\r\n        onBeforeShow?: () => void;\r\n        /** Override placement (default: `badgeTooltipPlacement`). */\r\n        placement?: Placement;\r\n        /** Override offset (default: `badgeTooltipOffset`). */\r\n        offsetDistance?: number;\r\n        /** Override show delay (default: `badgeTooltipDelay`). */\r\n        showDelay?: number;\r\n        /** Tooltip element CSS class (default: badge tooltip styling). */\r\n        cssClass?: string;\r\n        /** Visibility-toggle CSS class (default: badge tooltip visible class). */\r\n        visibleClass?: string;\r\n        /** Anchor to and follow the mouse pointer. */\r\n        followCursor?: boolean;\r\n    }"
+                    "text": "{\n        id: string;\n        trigger: HTMLElement;\n        content: string | HTMLElement;\n        onBeforeShow?: () => void;\n        /** Override placement (default: `badgeTooltipPlacement`). */\n        placement?: Placement;\n        /** Override offset (default: `badgeTooltipOffset`). */\n        offsetDistance?: number;\n        /** Override show delay (default: `badgeTooltipDelay`). */\n        showDelay?: number;\n        /** Tooltip element CSS class (default: badge tooltip styling). */\n        cssClass?: string;\n        /** Visibility-toggle CSS class (default: badge tooltip visible class). */\n        visibleClass?: string;\n        /** Anchor to and follow the mouse pointer. */\n        followCursor?: boolean;\n    }"
                   }
                 }
               ],
-              "description": "Create or replace a tracked tooltip with the given id. Replacing destroys the old one,\r\nwhich is the normal flow when re-rendering badges/actions."
+              "description": "Create or replace a tracked tooltip with the given id. Replacing destroys the old one,\nwhich is the normal flow when re-rendering badges/actions."
             },
             {
               "kind": "method",
@@ -2771,7 +2836,7 @@
                   "text": "void"
                 }
               },
-              "description": "Attach hover tooltips to the currently rendered dropdown options. Prunes existing option\r\ntooltips first, so it's safe to call on every render and on every virtual-scroll range change\r\n(where option DOM is recycled). Each option resolves its source object via `data-index` into\r\n`filteredOptions`, the same global index `renderOption` was given."
+              "description": "Attach hover tooltips to the currently rendered dropdown options. Prunes existing option\ntooltips first, so it's safe to call on every render and on every virtual-scroll range change\n(where option DOM is recycled). Each option resolves its source object via `data-index` into\n`filteredOptions`, the same global index `renderOption` was given."
             },
             {
               "kind": "method",
@@ -2782,7 +2847,7 @@
                   "text": "void"
                 }
               },
-              "description": "Tag each currently-rendered fullscreen option row whose title is horizontally\r\nclipped with `.ms__option--truncated`, so CSS reveals its info affordance.\r\nRuns per virtual-scroll render (rows recycle) and on the non-virtual render.\r\nHorizontal (ellipsis) overflow only — the truncation mode this pairs with;\r\na wrapping title isn't \"cut\", it grows vertically. No-op unless fullscreen."
+              "description": "Tag each currently-rendered fullscreen option row whose title is horizontally\nclipped with `.ms__option--truncated`, so CSS reveals its info affordance.\nRuns per virtual-scroll render (rows recycle) and on the non-virtual render.\nHorizontal (ellipsis) overflow only — the truncation mode this pairs with;\na wrapping title isn't \"cut\", it grows vertically. No-op unless fullscreen."
             },
             {
               "kind": "method",
@@ -2801,7 +2866,7 @@
                   }
                 }
               ],
-              "description": "Reveal (or dismiss) the full label of a clipped fullscreen row when its info\r\naffordance is tapped — hover tooltips don't fire on touch, and a hover tooltip's\r\nsynthetic mouseleave (from the tap itself, under devtools touch emulation) would\r\nflash it away. So this is a manually-controlled `createPopover` panel, mounted in\r\nthe shadow root for component styling, that stays until explicitly dismissed:\r\na second tap on the same button, a list scroll, a re-render, an outside tap, or\r\nclosing the panel (see hideLabelReveal + its call sites). Tapping the same button\r\nwhile it's shown toggles it off."
+              "description": "Reveal (or dismiss) the full label of a clipped fullscreen row when its info\naffordance is tapped — hover tooltips don't fire on touch, and a hover tooltip's\nsynthetic mouseleave (from the tap itself, under devtools touch emulation) would\nflash it away. So this is a manually-controlled `createPopover` panel, mounted in\nthe shadow root for component styling, that stays until explicitly dismissed:\na second tap on the same button, a list scroll, a re-render, an outside tap, or\nclosing the panel (see hideLabelReveal + its call sites). Tapping the same button\nwhile it's shown toggles it off."
             },
             {
               "kind": "method",
@@ -2838,7 +2903,7 @@
                   }
                 }
               ],
-              "description": "Show a transient message (\"toast\") on top of the component. Its reason for existing:\r\nin the fullscreen overlay the sheet covers the whole page, so a consumer can't surface\r\nfeedback (a blocked veto, a hint) where the user can see it. This renders above the\r\npanel in BOTH presentations — anchored under the control when floating, pinned to the\r\nbottom of the viewport (over the overlay) when fullscreen.\r\n\r\nContent is a string (plain text) or an HTMLElement (rich markup). `opts.variant`\r\n(info | warning | error | success) picks the tone; `opts.duration` sets auto-dismiss\r\n(0 = sticky). Tapping the message dismisses it. Only one shows at a time — a new call\r\nreplaces the previous. Also reached automatically when a veto callback returns a string."
+              "description": "Show a transient message (\"toast\") on top of the component. Its reason for existing:\nin the fullscreen overlay the sheet covers the whole page, so a consumer can't surface\nfeedback (a blocked veto, a hint) where the user can see it. This renders above the\npanel in BOTH presentations — anchored under the control when floating, pinned to the\nbottom of the viewport (over the overlay) when fullscreen.\n\nContent is a string (plain text) or an HTMLElement (rich markup). `opts.variant`\n(info | warning | error | success) picks the tone; `opts.duration` sets auto-dismiss\n(0 = sticky). Tapping the message dismisses it. Only one shows at a time — a new call\nreplaces the previous. Also reached automatically when a veto callback returns a string."
             },
             {
               "kind": "method",
@@ -2860,7 +2925,7 @@
                   "text": "void"
                 }
               },
-              "description": "Hide (don't destroy) every currently-shown option tooltip immediately,\r\nignoring the hide delay. Wired to dropdown scroll so a tooltip can't trail\r\nits recycling/scrolling anchor row. Handles stay in the map; a fresh hover\r\nre-shows them."
+              "description": "Hide (don't destroy) every currently-shown option tooltip immediately,\nignoring the hide delay. Wired to dropdown scroll so a tooltip can't trail\nits recycling/scrolling anchor row. Handles stay in the map; a fresh hover\nre-shows them."
             },
             {
               "kind": "method",
@@ -2871,7 +2936,7 @@
                   "text": "void"
                 }
               },
-              "description": "Destroy only the option tooltips (prefixed `option-`). Called before re-rendering or\r\nrecycling the options list so per-option tooltip state doesn't leak."
+              "description": "Destroy only the option tooltips (prefixed `option-`). Called before re-rendering or\nrecycling the options list so per-option tooltip state doesn't leak."
             },
             {
               "kind": "method",
@@ -2892,7 +2957,7 @@
                   "text": "void"
                 }
               },
-              "description": "Destroy only the action-button tooltips. Called from `renderDropdown`/`renderDropdownVirtual`\r\nbefore rebuilding the actions row, so per-button tooltip state doesn't leak."
+              "description": "Destroy only the action-button tooltips. Called from `renderDropdown`/`renderDropdownVirtual`\nbefore rebuilding the actions row, so per-button tooltip state doesn't leak."
             },
             {
               "kind": "method",
@@ -2903,7 +2968,7 @@
                   "text": "void"
                 }
               },
-              "description": "Destroy main-badges-container tooltips. Called before re-rendering the badges container.\r\nPopover tooltips (prefixed `popover-`) survive — they're owned by the popover lifecycle and\r\ncleaned up in `hideSelectedPopover`. Action-button tooltips (prefixed `action-`) survive too."
+              "description": "Destroy main-badges-container tooltips. Called before re-rendering the badges container.\nPopover tooltips (prefixed `popover-`) survive — they're owned by the popover lifecycle and\ncleaned up in `hideSelectedPopover`. Action-button tooltips (prefixed `action-`) survive too."
             },
             {
               "kind": "method",
@@ -3393,7 +3458,7 @@
               "name": "inputs",
               "privacy": "protected",
               "static": true,
-              "default": "[ // ── Strings (cosmetic → update). Optional ones are nullable: absent → null ─ { configKey: 'searchHint', attribute: 'search-hint', converter: toText({ isNullable: true }), on: 'update', description: 'Small hint text shown beneath the search input.' }, { configKey: 'searchPlaceholder', attribute: 'search-placeholder', converter: toText({ isNullable: true }), on: 'update', description: 'Placeholder text for the search input. When unset it defaults to \"Search...\"; if `show-search-mode-toggle` is on, the default instead becomes mode-aware (\"Search…\" in navigate, \"Filter…\" in filter). An explicit value always wins and stays fixed.' }, { configKey: 'selectPlaceholder', attribute: 'select-placeholder', converter: toText({ default: 'Pick an option...' }), on: 'update', description: 'Placeholder shown on the control when nothing is selected.' }, { configKey: 'noDataPlaceholder', attribute: 'no-data-placeholder', converter: toText({ isNullable: true }), on: 'update', description: 'Text shown when there are no options at all.' }, { configKey: 'dropdownMinWidth', attribute: 'dropdown-min-width', converter: toText({ isNullable: true }), on: 'update', description: 'Minimum width of the dropdown panel (any CSS length).' }, { configKey: 'dropdownMaxWidth', attribute: 'dropdown-max-width', converter: toText({ isNullable: true }), on: 'update', description: 'Maximum width of the dropdown panel (any CSS length).' }, { configKey: 'maxHeight', attribute: 'max-height', converter: toText({ default: '20rem' }), on: 'update', description: 'Maximum height of the dropdown list before it scrolls.' }, { configKey: 'emptyMessage', attribute: 'empty-message', converter: toText({ default: 'No results found' }), on: 'update', description: 'Message shown when a search yields no matches.' }, { configKey: 'loadingMessage', attribute: 'loading-message', converter: toText({ default: 'Loading...' }), on: 'update', description: 'Message shown while options are loading.' }, { configKey: 'removeButtonTooltipText', attribute: 'remove-button-tooltip-text', converter: toText({ isNullable: true }), on: 'update', description: 'Tooltip text for a badge remove (×) button.' }, { configKey: 'formFieldId', attribute: 'name', converter: toText({ isNullable: true }), on: 'reinit', description: 'HTML form field name/id used for the hidden input(s).' }, // ── CSS-var sugar (mirrored to a host style prop in reinit()/update()) ──── { configKey: 'dropdownWidth', attribute: 'dropdown-width', converter: toText({ isNullable: true }), on: 'update', description: 'Fixed dropdown width; mirrored to the `--ms-dropdown-width` CSS variable.' }, { configKey: 'selectedPopoverWidth', attribute: 'selected-popover-width', converter: toText({ isNullable: true }), on: 'update', description: 'Selected-items popover width; mirrored to `--ms-selected-popover-width`.' }, // ── Member properties (structural → reinit; optional → nullable) ───────── { configKey: 'valueMember', attribute: 'value-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name on an option object that holds its value.' }, { configKey: 'displayValueMember', attribute: 'display-value-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that holds an option display label.' }, { configKey: 'searchValueMember', attribute: 'search-value-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name searched against (falls back to the display value).' }, { configKey: 'iconMember', attribute: 'icon-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that holds an option icon.' }, { configKey: 'subtitleMember', attribute: 'subtitle-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that holds an option subtitle.' }, { configKey: 'fullTitleMember', attribute: 'full-title-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that holds an option full/long title.' }, { configKey: 'groupMember', attribute: 'group-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name used to group options under headers.' }, { configKey: 'disabledMember', attribute: 'disabled-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that marks an option disabled.' }, // ── Tree of options (structural → reinit; optional → nullable) ─────────── { configKey: 'pathMember', attribute: 'path-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name holding a node materialized tree path.' }, { configKey: 'parentPathMember', attribute: 'parent-path-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name holding a node parent path.' }, { configKey: 'levelMember', attribute: 'level-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name holding a node depth level.' }, { configKey: 'hasChildrenMember', attribute: 'has-children-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name flagging that a node has children.' }, { configKey: 'isSelectableMember', attribute: 'is-selectable-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name marking whether a node can be selected.' }, { configKey: 'treePathSeparator', attribute: 'tree-path-separator', converter: toText({ default: '.' }), reflect: true, on: 'reinit', description: 'Separator between segments in a materialized tree path.' }, { configKey: 'isTreeEnabled', converter: toBool('tristate'), on: 'reinit', type: 'boolean', description: 'Force tree mode on/off. Property-only; when unset (null) tree mode auto-enables if a path source (path-member / getPathCallback) is present.' }, { configKey: 'checkboxMode', attribute: 'checkbox-mode', converter: toEnum(['independent', 'cascade'] as const, { default: 'independent' }), reflect: true, on: 'update', description: `Tree checkbox interaction. - \\`independent\\` (default) — toggles only the clicked node. - \\`cascade\\` — checks a node whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches. Tree + multiple only.` }, { configKey: 'cascadeSelectPolicy', attribute: 'cascade-select-policy', converter: toEnum(['rolled-up', 'leaves', 'all'] as const, { default: 'rolled-up' }), reflect: true, on: 'update', description: `In \\`cascade\\` mode, which values a selection emits (badges / form / change): - \\`rolled-up\\` (default) — minimal cover: a fully-selected subtree collapses to its root; partially-selected branches emit their individually-checked descendants. - \\`leaves\\` — only the checked leaf-level nodes. - \\`all\\` — every fully-checked node (branches and leaves).` }, // ── Enums ──────────────────────────────────────────────────────────────── { configKey: 'badgesDisplayMode', attribute: 'badges-display-mode', converter: toEnum(['badges', 'count', 'compact', 'partial', 'none'] as const, { default: 'badges' }), on: 'reinit', description: 'How the current selection is shown in the control.' }, { configKey: 'badgesPosition', attribute: 'badges-position', converter: toEnum(['top', 'bottom', 'left', 'right'] as const, { default: 'bottom' }), on: 'reinit', description: 'Where the badges/selection appear relative to the input.' }, { configKey: 'badgesThresholdMode', attribute: 'badges-threshold-mode', converter: toEnum(['count', 'partial'] as const, { default: 'count' }), on: 'update', description: 'How `badgesThreshold` is interpreted: collapse to a count badge, or keep partial badges + a \"more\" badge.' }, { configKey: 'searchInputMode', attribute: 'search-input-mode', converter: toEnum(['normal', 'readonly', 'hidden'] as const, { default: 'normal' }), on: 'reinit', description: 'Search field mode: editable, read-only, or hidden.' }, { configKey: 'searchMode', attribute: 'search-mode', converter: toEnum(['filter', 'navigate'] as const, { default: 'filter' }), on: 'reinit', description: 'Whether typing filters the list or navigates it.' }, { configKey: 'actionsLayout', attribute: 'actions-layout', converter: toEnum(['nowrap', 'wrap'] as const, { default: 'nowrap' }), on: 'reinit', description: 'Whether the action bar wraps or stays on one line.' }, { configKey: 'actionsPosition', attribute: 'actions-position', converter: toEnum(['top', 'bottom'] as const, { default: 'top' }), on: 'reinit', description: 'Whether the action bar sits above or below the list.' }, { configKey: 'actionsAlign', attribute: 'actions-align', converter: toEnum(['stretch', 'left', 'right', 'center', 'space-between'] as const, { default: 'stretch' }), on: 'update', description: 'Horizontal alignment of the action buttons.' }, { configKey: 'checkboxAlign', attribute: 'checkbox-align', converter: toEnum(['top', 'center', 'bottom'] as const, { default: 'center' }), on: 'update', description: 'Vertical alignment of an option checkbox.' }, { configKey: 'valueFormat', attribute: 'value-format', converter: toEnum(['json', 'csv', 'array'] as const, { default: 'json' }), on: 'reinit', description: 'Serialization format the control emits its value in.' }, { configKey: 'badgeTooltipPlacement', attribute: 'badge-tooltip-placement', converter: toEnum(PLACEMENTS, { default: 'top' }), on: 'update', description: 'Preferred placement of a badge tooltip relative to its badge (floating-ui placement).' }, { configKey: 'optionTooltipPlacement', attribute: 'option-tooltip-placement', converter: toEnum(PLACEMENTS, { default: 'top-start' }), on: 'update', description: 'Preferred placement of an option tooltip (floating-ui placement).' }, { configKey: 'mobilePresentation', attribute: 'mobile-presentation', converter: toEnum(['auto', 'floating', 'fullscreen'] as const, { default: 'auto' }), reflect: true, on: 'update', description: 'How the open dropdown is presented on phones. `auto` (default) keeps the floating panel on desktop/tablet and switches to a full-screen overlay on phone-sized touch devices (touch primary + shorter viewport side < 600px, orientation-robust); `floating` forces the anchored panel everywhere; `fullscreen` forces the full-screen overlay on any device (handy for previews/testing). Resolved reactively from the device/viewport environment.' }, { configKey: 'fullscreenAutofocus', attribute: 'fullscreen-autofocus', converter: toBool('default-false'), on: 'update', description: 'In the phone fullscreen overlay, auto-focus the search field on open (pops the soft keyboard immediately). Default `false`: the sheet opens with the list visible and the keyboard closed, appearing only when the user taps the search. Set `true` to type-to-filter right away. No effect in the floating presentation.' }, // ── Numbers ────────────────────────────────────────────────────────────── { configKey: 'badgesThreshold', attribute: 'badges-threshold', converter: toInt(), on: 'update', description: 'Threshold at which badges collapse to a count/compact view.' }, { configKey: 'badgesMaxVisible', attribute: 'badges-max-visible', converter: toInt(), on: 'update', description: 'Maximum number of badges rendered before overflow.' }, { configKey: 'collapseBadgesBelow', attribute: 'collapse-badges-below', converter: toInt(), on: 'update', description: 'Container-responsive opt-in (off by default). When set to a px width, the control watches its OWN border box (not the window, via the core `resized` hook / a shared ResizeObserver) and collapses `badges-display-mode` to `count` (\"N selected\") while the box is narrower than this — so a picker in a narrow column/sidebar never overflows with pills, even on a wide monitor. Widening past the threshold restores the configured badges mode. Element-only: the override is applied to the live picker, never to your `badges-display-mode` config.' }, { configKey: 'minSearchLength', attribute: 'min-search-length', converter: toInt({ default: 0 }), on: 'update', description: 'Minimum characters before searching/filtering starts.' }, { configKey: 'searchDebounce', attribute: 'search-debounce', converter: toInt({ default: 0 }), on: 'update', description: 'Debounce delay in ms applied to the search input.' }, { configKey: 'virtualScrollThreshold', attribute: 'virtual-scroll-threshold', converter: toInt({ default: 100 }), on: 'reinit', description: 'Option count above which virtual scrolling turns on.' }, { configKey: 'optionHeight', attribute: 'option-height', converter: toInt({ default: 50 }), on: 'update', description: 'Fixed row height in px used by virtual scrolling.' }, { configKey: 'badgeHeight', attribute: 'badge-height', converter: toInt({ default: 36 }), on: 'update', description: 'Fixed badge height in px used for layout/virtualization.' }, { configKey: 'virtualScrollBuffer', attribute: 'virtual-scroll-buffer', converter: toInt({ default: 10 }), on: 'update', description: 'Extra rows rendered above/below the viewport when virtualizing.' }, { configKey: 'badgeTooltipDelay', attribute: 'badge-tooltip-delay', converter: toInt({ default: 100 }), on: 'update', description: 'Delay in ms before a badge tooltip appears.' }, { configKey: 'badgeTooltipOffset', attribute: 'badge-tooltip-offset', converter: toInt({ default: 8 }), on: 'update', description: 'Gap in px between a badge and its tooltip.' }, { configKey: 'optionTooltipDelay', attribute: 'option-tooltip-delay', converter: toInt(), on: 'update', description: 'Delay in ms before an option tooltip appears (falls back to badgeTooltipDelay).' }, { configKey: 'optionTooltipOffset', attribute: 'option-tooltip-offset', converter: toInt(), on: 'update', description: 'Gap in px between an option and its tooltip.' }, // ── Booleans (default true) ────────────────────────────────────────────── { configKey: 'isMultipleEnabled', attribute: 'multiple', converter: toBool('default-true'), on: 'reinit', description: 'Allow selecting multiple options. When off, selecting one replaces the previous.' }, { configKey: 'isGroupsAllowed', attribute: 'allow-groups', converter: toBool('default-true'), on: 'reinit', description: 'Allow grouping options under group headers.' }, { configKey: 'isCheckboxesShown', attribute: 'show-checkboxes', converter: toBool('default-true'), on: 'reinit', description: 'Show a checkbox on each option.' }, { configKey: 'isActionsSticky', attribute: 'sticky-actions', converter: toBool('default-true'), on: 'update', description: 'Keep the action bar pinned while the list scrolls.' }, { configKey: 'isPlacementLocked', attribute: 'lock-placement', converter: toBool('default-true'), on: 'update', description: 'Keep the dropdown initial placement instead of flipping when it fits.' }, { configKey: 'isSearchEnabled', attribute: 'enable-search', converter: toBool('default-true'), on: 'reinit', description: 'Show the search input.' }, { configKey: 'isKeepOptionsOnSearch', attribute: 'keep-options-on-search', converter: toBool('default-true'), on: 'update', description: 'Keep already-selected options visible while filtering.' }, { configKey: 'shouldKeepSearchOnClose', attribute: 'should-keep-search-on-close', converter: toBool('default-true'), on: 'update', description: 'Preserve the search text after the dropdown closes.' }, { configKey: 'isSelectedPopoverEnabled', attribute: 'enable-selected-popover', converter: toBool('default-true'), on: 'update', description: 'Allow the selected-items popover to open (from the count/compact/\"+X more\" badge or the in-input counter). Turn off when you render your own selection UI, so those affordances become inert.' }, // ── Booleans (default false) ───────────────────────────────────────────── { configKey: 'isCloseOnSelect', attribute: 'close-on-select', converter: toBool('default-false'), on: 'update', description: 'Close the dropdown immediately after a selection.' }, { configKey: 'isAddNewAllowed', attribute: 'allow-add-new', converter: toBool('default-false'), on: 'reinit', description: 'Allow adding a new option from the search text.' }, { configKey: 'isCounterShown', attribute: 'show-counter', converter: toBool('default-false'), on: 'update', description: 'Show a selected-count indicator.' }, { configKey: 'isBadgeFullTitleShown', attribute: 'show-badge-full-title', converter: toBool('default-false'), on: 'update', description: 'Show the full title on badges instead of the short label.' }, { configKey: 'isVirtualScrollEnabled', attribute: 'enable-virtual-scroll', converter: toBool('default-false'), on: 'reinit', description: 'Force virtual scrolling on regardless of the threshold.' }, { configKey: 'isBadgeTooltipsEnabled', attribute: 'enable-badge-tooltips', converter: toBool('default-false'), on: 'update', description: 'Enable tooltips on badges.' }, { configKey: 'isOptionTooltipsEnabled', attribute: 'enable-option-tooltips', converter: toBool('default-false'), on: 'update', description: 'Enable tooltips on options.' }, { configKey: 'isOptionTooltipFollowCursor', attribute: 'option-tooltip-follow-cursor', converter: toBool('default-false'), on: 'update', description: 'Make option tooltips follow the pointer.' }, { configKey: 'isSearchModeToggleShown', attribute: 'show-search-mode-toggle', converter: toBool('default-false'), on: 'update', description: 'Show a clickable toggle in the phone fullscreen overlay search header that flips `search-mode` between `filter` and `navigate` live. Fullscreen-only; no effect in the floating presentation or when search is disabled.' }, // ── Special attributes ─────────────────────────────────────────────────── { configKey: 'initialValues', attribute: 'initial-values', converter: toInitialValues(), default: [], on: 'reinit', type: 'Array<string | number>', description: 'Values selected on first render. Accepts a JSON array (`[\"a\",\"b\"]`) or a bare CSV (`a,b,c`).' }, { configKey: 'showDebugInfo', attribute: 'show-debug-info', converter: toBool('default-false'), on: 'update', description: 'Render an in-component debug panel.', deprecated: 'Use per-instance logging (el.enableLogging()) instead.' }, // ── Complex property (data) ────────────────────────────────────────────── { configKey: 'options', converter: toObjectArray(), on: 'reinit', type: 'ReadonlyArray<Record<string, unknown>>', 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.' }, { configKey: 'optionsSource', attribute: 'data-options', converter: toText({ isNullable: true }), on: 'reinit', type: 'string', 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.' }, { configKey: 'optionsFormat', attribute: 'data-options-format', converter: toEnum(OPTIONS_FORMATS, { default: 'json' }), on: 'reinit', type: \"'json' | 'csv' | 'plain'\", description: 'How to parse the `data-options` attribute: `json` (a JSON array of objects or [value, label] tuples), `csv` (rows split on `data-options-row-splitter`, cells on `data-options-splitter`; the first row is a header — map columns via *-member), or `plain` (bare values split on both splitters -> [value, label] tuples, value === label). Default `json`.' }, { configKey: 'optionsSplitter', attribute: 'data-options-splitter', converter: toText({ default: ',' }), on: 'reinit', type: 'string', description: 'Field/cell delimiter for the `csv` and `plain` `data-options` formats. Default `,`. Escapes `\\\\t` `\\\\n` `\\\\r` are honoured (e.g. `data-options-splitter=\"\\\\t\"` for TSV). Ignored for `json`.' }, { configKey: 'optionsRowSplitter', attribute: 'data-options-row-splitter', converter: toText({ default: '\\n' }), on: 'reinit', type: 'string', description: 'Row/record delimiter for the `csv` and `plain` `data-options` formats. Default newline. Escapes honoured (e.g. `data-options-row-splitter=\";\"` for single-line data). Ignored for `json`.' }, { configKey: 'actionButtons', converter: toValue({ validate: (v): v is unknown[] => Array.isArray(v) }), on: 'reinit', type: 'Array<Record<string, unknown>>', description: 'Custom action buttons for the dropdown footer/header. Property-only; when unset the default Select-All / Clear buttons apply.' }, // ── Callbacks: data shape (structural → reinit) ────────────────────────── { configKey: 'getValueCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => string | number', description: 'Extract an option value (overrides valueMember).' }, { configKey: 'getPathCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => string', description: 'Extract a node tree path (enables tree mode; overrides pathMember).' }, { configKey: 'getGroupCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => string', description: 'Extract the group name from an option (overrides groupMember).' }, { configKey: 'getDisabledCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => boolean', description: 'Whether an option is disabled (overrides disabledMember).' }, { configKey: 'getIsSelectableCallback', converter: cb(), on: 'reinit', type: '(node: unknown) => boolean', description: 'Whether a tree node can be selected (overrides is-selectable-member).' }, { configKey: 'getSearchValueCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => string', description: 'Text an option is searched against (overrides searchValueMember).' }, { configKey: 'searchCallback', converter: cb(), on: 'reinit', type: '(searchTerm: string, signal?: AbortSignal) => Promise<unknown[]>', description: 'Custom / async search; return the filtered options.' }, // ── Callbacks: display / render (cosmetic → update) ────────────────────── { configKey: 'getDisplayValueCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Compute the display label for an option (overrides displayValueMember).' }, { configKey: 'getBadgeDisplayCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Compute the text shown on an option badge.' }, { configKey: 'getBadgeClassCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | string[]', description: 'Extra CSS class(es) for an option badge.' }, { configKey: 'getIconCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Icon for an option (overrides iconMember).' }, { configKey: 'getSubtitleCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Subtitle for an option (overrides subtitleMember).' }, { configKey: 'getFullTitleCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Full title for an option (used by badges when show-badge-full-title is on).' }, { configKey: 'getCounterCallback', converter: cb(), on: 'update', type: '(count: number, moreCount?: number) => string', description: 'Render the selected-count label.' }, { configKey: 'getValueFormatCallback', converter: cb(), on: 'update', type: '(selectedValues: (string | number)[]) => string', description: 'Serialize the selected values for form submission.' }, { configKey: 'getBadgeTooltipCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | HTMLElement', description: 'Tooltip content for an option badge.' }, { configKey: 'getOptionTooltipCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | HTMLElement', description: 'Tooltip content for an option row.' }, { configKey: 'getRemoveButtonTooltipCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Tooltip text for a badge remove button.' }, { configKey: 'getSelectedItemClassCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | string[]', description: 'Extra CSS class(es) for a selected item.' }, { configKey: 'renderOptionContentCallback', converter: cb(), on: 'update', type: '(item: unknown, context: OptionContentRenderContext) => string | HTMLElement', description: 'Custom render for an option row; may return HTML or an element.' }, { configKey: 'renderBadgeContentCallback', converter: cb(), on: 'update', type: '(item: unknown, context: BadgeContentRenderContext) => string | HTMLElement', description: 'Custom render for a badge content (fills the built-in pill); may return HTML or an element.' }, { configKey: 'renderBadgeCallback', converter: cb(), on: 'update', type: '(item: unknown, context: BadgeContentRenderContext) => string | HTMLElement | null', description: 'Custom render for the WHOLE badge (main area), not just its content — return the entire pill/card. The component wraps it in `.ms__badge.ms__badge--custom` with `data-value` and delegates removal to any inner element with `data-action=\"remove\"` (or `.ms__badge-remove`). Return null/empty to fall back to the default pill for that item.' }, { configKey: 'renderGroupLabelContentCallback', converter: cb(), on: 'update', type: '(groupName: string) => string | HTMLElement', description: 'Customize a group label; may return an HTML string or element.' }, { configKey: 'renderSelectedContentCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Custom render for the whole selected area.' }, { configKey: 'renderSelectedItemContentCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | HTMLElement', description: 'Custom render for one selected item.' }, { configKey: 'customStylesCallback', converter: cb(), on: 'update', type: '() => string', description: 'Returns a CSS string injected into the component via a replaceable style slot (§12.8).' }, // ── Callbacks: before-hooks (behavior-shaping) ─────────────────────────── { configKey: 'beforeSearchCallback', converter: cb(), on: 'update', type: '(searchTerm: string) => string | null', description: 'Runs before a search; return a rewritten term or null to veto.' }, { configKey: 'beforeSelectCallback', converter: cb(), on: 'update', type: '(option: unknown, selectedOptions: unknown[]) => boolean | string | void', description: 'Runs before selecting; return false to veto, or a string to veto and show it as a message.' }, { configKey: 'beforeDeselectCallback', converter: cb(), on: 'update', type: '(option: unknown, selectedOptions: unknown[]) => boolean | string | void', description: 'Runs before deselecting; return false to veto, or a string to veto and show it as a message.' }, { configKey: 'addNewCallback', converter: cb(), on: 'update', type: '(value: string) => unknown | Promise<unknown>', description: 'Create a new option from the typed text.' }, { configKey: 'keydownCallback', converter: cb(), on: 'update', type: '(context: MultiSelectKeydownContext) => boolean | void', description: 'Intercept keydown before built-in handling; return true to suppress the default. Gets the event, current state, and an imperative controller.' }, ]",
+              "default": "[ // ── Strings (cosmetic → update). Optional ones are nullable: absent → null ─ { configKey: 'searchHint', attribute: 'search-hint', converter: toText({ isNullable: true }), on: 'update', description: 'Small hint text shown beneath the search input.' }, { configKey: 'searchPlaceholder', attribute: 'search-placeholder', converter: toText({ isNullable: true }), on: 'update', description: 'Placeholder text for the search input. When unset it defaults to \"Search...\"; if `show-search-mode-toggle` is on, the default instead becomes mode-aware (\"Search…\" in navigate, \"Filter…\" in filter). An explicit value always wins and stays fixed.' }, { configKey: 'selectPlaceholder', attribute: 'select-placeholder', converter: toText({ default: 'Pick an option...' }), on: 'update', description: 'Placeholder shown on the control when nothing is selected.' }, { configKey: 'noDataPlaceholder', attribute: 'no-data-placeholder', converter: toText({ isNullable: true }), on: 'update', description: 'Text shown when there are no options at all.' }, { configKey: 'dropdownMinWidth', attribute: 'dropdown-min-width', converter: toText({ isNullable: true }), on: 'update', description: 'Minimum width of the dropdown panel (any CSS length).' }, { configKey: 'dropdownMaxWidth', attribute: 'dropdown-max-width', converter: toText({ isNullable: true }), on: 'update', description: 'Maximum width of the dropdown panel (any CSS length).' }, { configKey: 'maxHeight', attribute: 'max-height', converter: toText({ default: '20rem' }), on: 'update', description: 'Maximum height of the dropdown list before it scrolls.' }, { configKey: 'emptyMessage', attribute: 'empty-message', converter: toText({ default: 'No results found' }), on: 'update', description: 'Message shown when a search yields no matches.' }, { configKey: 'loadingMessage', attribute: 'loading-message', converter: toText({ default: 'Loading...' }), on: 'update', description: 'Message shown while options are loading.' }, { configKey: 'removeButtonTooltipText', attribute: 'remove-button-tooltip-text', converter: toText({ isNullable: true }), on: 'update', description: 'Tooltip text for a badge remove (×) button.' }, { configKey: 'formFieldId', attribute: 'name', converter: toText({ isNullable: true }), on: 'reinit', description: 'HTML form field name/id used for the hidden input(s).' }, // ── CSS-var sugar (mirrored to a host style prop in reinit()/update()) ──── { configKey: 'dropdownWidth', attribute: 'dropdown-width', converter: toText({ isNullable: true }), on: 'update', description: 'Fixed dropdown width; mirrored to the `--ms-dropdown-width` CSS variable.' }, { configKey: 'selectedPopoverWidth', attribute: 'selected-popover-width', converter: toText({ isNullable: true }), on: 'update', description: 'Selected-items popover width; mirrored to `--ms-selected-popover-width`.' }, // ── Member properties (structural → reinit; optional → nullable) ───────── { configKey: 'valueMember', attribute: 'value-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name on an option object that holds its value.' }, { configKey: 'displayValueMember', attribute: 'display-value-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that holds an option display label.' }, { configKey: 'searchValueMember', attribute: 'search-value-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name searched against (falls back to the display value).' }, { configKey: 'iconMember', attribute: 'icon-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that holds an option icon.' }, { configKey: 'subtitleMember', attribute: 'subtitle-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that holds an option subtitle.' }, { configKey: 'fullTitleMember', attribute: 'full-title-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that holds an option full/long title.' }, { configKey: 'groupMember', attribute: 'group-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name used to group options under headers.' }, { configKey: 'disabledMember', attribute: 'disabled-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name that marks an option disabled.' }, // ── Tree of options (structural → reinit; optional → nullable) ─────────── { configKey: 'pathMember', attribute: 'path-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name holding a node materialized tree path.' }, { configKey: 'parentPathMember', attribute: 'parent-path-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name holding a node parent path.' }, { configKey: 'levelMember', attribute: 'level-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name holding a node depth level.' }, { configKey: 'hasChildrenMember', attribute: 'has-children-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name flagging that a node has children.' }, { configKey: 'isSelectableMember', attribute: 'is-selectable-member', converter: toText({ isNullable: true }), reflect: true, on: 'reinit', description: 'Property name marking whether a node can be selected.' }, { configKey: 'treePathSeparator', attribute: 'tree-path-separator', converter: toText({ default: '.' }), reflect: true, on: 'reinit', description: 'Separator between segments in a materialized tree path.' }, { configKey: 'isTreeEnabled', converter: toBool('tristate'), on: 'reinit', type: 'boolean', description: 'Force tree mode on/off. Property-only; when unset (null) tree mode auto-enables if a path source (path-member / getPathCallback) is present.' }, { configKey: 'checkboxMode', attribute: 'checkbox-mode', converter: toEnum(['independent', 'cascade'] as const, { default: 'independent' }), reflect: true, on: 'update', description: `Tree checkbox interaction. - \\`independent\\` (default) — toggles only the clicked node. - \\`cascade\\` — checks a node whole subtree and shows a tristate (checked / indeterminate / unchecked) box on branches. Tree + multiple only.` }, { configKey: 'cascadeSelectPolicy', attribute: 'cascade-select-policy', converter: toEnum(['rolled-up', 'leaves', 'all'] as const, { default: 'rolled-up' }), reflect: true, on: 'update', description: `In \\`cascade\\` mode, which values a selection emits (badges / form / change): - \\`rolled-up\\` (default) — minimal cover: a fully-selected subtree collapses to its root; partially-selected branches emit their individually-checked descendants. - \\`leaves\\` — only the checked leaf-level nodes. - \\`all\\` — every fully-checked node (branches and leaves).` }, // ── Enums ──────────────────────────────────────────────────────────────── { configKey: 'badgesDisplayMode', attribute: 'badges-display-mode', converter: toEnum(['badges', 'count', 'compact', 'partial', 'none'] as const, { default: 'badges' }), on: 'reinit', description: 'How the current selection is shown in the control.' }, { configKey: 'badgesPosition', attribute: 'badges-position', converter: toEnum(['top', 'bottom', 'left', 'right'] as const, { default: 'bottom' }), on: 'reinit', description: 'Where the badges/selection appear relative to the input.' }, { configKey: 'badgesThresholdMode', attribute: 'badges-threshold-mode', converter: toEnum(['count', 'partial'] as const, { default: 'count' }), on: 'update', description: 'How `badgesThreshold` is interpreted: collapse to a count badge, or keep partial badges + a \"more\" badge.' }, { configKey: 'searchInputMode', attribute: 'search-input-mode', converter: toEnum(['normal', 'readonly', 'hidden'] as const, { default: 'normal' }), on: 'reinit', description: 'Search field mode: editable, read-only, or hidden.' }, { configKey: 'searchMode', attribute: 'search-mode', converter: toEnum(['filter', 'navigate'] as const, { default: 'filter' }), on: 'reinit', description: 'Whether typing filters the list or navigates it.' }, { configKey: 'overlayGroup', attribute: 'overlay-group', converter: toText({ isNullable: true }), on: 'reinit', description: 'Scope the \"one overlay open at a time\" coordination to a named group. Overlays (multiselects, datepickers, external popovers) sharing a group dismiss each other when one opens; different groups are independent. Unset = the default (ungrouped) group.' }, { configKey: 'actionsLayout', attribute: 'actions-layout', converter: toEnum(['nowrap', 'wrap'] as const, { default: 'nowrap' }), on: 'reinit', description: 'Whether the action bar wraps or stays on one line.' }, { configKey: 'actionsPosition', attribute: 'actions-position', converter: toEnum(['top', 'bottom'] as const, { default: 'top' }), on: 'reinit', description: 'Whether the action bar sits above or below the list.' }, { configKey: 'actionsAlign', attribute: 'actions-align', converter: toEnum(['stretch', 'left', 'right', 'center', 'space-between'] as const, { default: 'stretch' }), on: 'update', description: 'Horizontal alignment of the action buttons.' }, { configKey: 'checkboxAlign', attribute: 'checkbox-align', converter: toEnum(['top', 'center', 'bottom'] as const, { default: 'center' }), on: 'update', description: 'Vertical alignment of an option checkbox.' }, { configKey: 'valueFormat', attribute: 'value-format', converter: toEnum(['json', 'csv', 'array'] as const, { default: 'json' }), on: 'reinit', description: 'Serialization format the control emits its value in.' }, { configKey: 'badgeTooltipPlacement', attribute: 'badge-tooltip-placement', converter: toEnum(PLACEMENTS, { default: 'top' }), on: 'update', description: 'Preferred placement of a badge tooltip relative to its badge (floating-ui placement).' }, { configKey: 'optionTooltipPlacement', attribute: 'option-tooltip-placement', converter: toEnum(PLACEMENTS, { default: 'top-start' }), on: 'update', description: 'Preferred placement of an option tooltip (floating-ui placement).' }, { configKey: 'mobilePresentation', attribute: 'mobile-presentation', converter: toEnum(['auto', 'floating', 'fullscreen'] as const, { default: 'auto' }), reflect: true, on: 'update', description: 'How the open dropdown is presented on phones. `auto` (default) keeps the floating panel on desktop/tablet and switches to a full-screen overlay on phone-sized touch devices (touch primary + shorter viewport side < 600px, orientation-robust); `floating` forces the anchored panel everywhere; `fullscreen` forces the full-screen overlay on any device (handy for previews/testing). Resolved reactively from the device/viewport environment.' }, { configKey: 'fullscreenAutofocus', attribute: 'fullscreen-autofocus', converter: toBool('default-false'), on: 'update', description: 'In the phone fullscreen overlay, auto-focus the search field on open (pops the soft keyboard immediately). Default `false`: the sheet opens with the list visible and the keyboard closed, appearing only when the user taps the search. Set `true` to type-to-filter right away. No effect in the floating presentation.' }, // ── Numbers ────────────────────────────────────────────────────────────── { configKey: 'badgesThreshold', attribute: 'badges-threshold', converter: toInt(), on: 'update', description: 'Threshold at which badges collapse to a count/compact view.' }, { configKey: 'badgesMaxVisible', attribute: 'badges-max-visible', converter: toInt(), on: 'update', description: 'Maximum number of badges rendered before overflow.' }, { configKey: 'collapseBadgesBelow', attribute: 'collapse-badges-below', converter: toInt(), on: 'update', description: 'Container-responsive opt-in (off by default). When set to a px width, the control watches its OWN border box (not the window, via the core `resized` hook / a shared ResizeObserver) and collapses `badges-display-mode` to `count` (\"N selected\") while the box is narrower than this — so a picker in a narrow column/sidebar never overflows with pills, even on a wide monitor. Widening past the threshold restores the configured badges mode. Element-only: the override is applied to the live picker, never to your `badges-display-mode` config.' }, { configKey: 'minSearchLength', attribute: 'min-search-length', converter: toInt({ default: 0 }), on: 'update', description: 'Minimum characters before searching/filtering starts.' }, { configKey: 'searchDebounce', attribute: 'search-debounce', converter: toInt({ default: 0 }), on: 'update', description: 'Debounce delay in ms applied to the search input.' }, { configKey: 'virtualScrollThreshold', attribute: 'virtual-scroll-threshold', converter: toInt({ default: 100 }), on: 'reinit', description: 'Option count above which virtual scrolling turns on.' }, { configKey: 'optionHeight', attribute: 'option-height', converter: toInt({ default: 50 }), on: 'update', description: 'Fixed row height in px used by virtual scrolling.' }, { configKey: 'badgeHeight', attribute: 'badge-height', converter: toInt({ default: 36 }), on: 'update', description: 'Fixed badge height in px used for layout/virtualization.' }, { configKey: 'virtualScrollBuffer', attribute: 'virtual-scroll-buffer', converter: toInt({ default: 10 }), on: 'update', description: 'Extra rows rendered above/below the viewport when virtualizing.' }, { configKey: 'badgeTooltipDelay', attribute: 'badge-tooltip-delay', converter: toInt({ default: 100 }), on: 'update', description: 'Delay in ms before a badge tooltip appears.' }, { configKey: 'badgeTooltipOffset', attribute: 'badge-tooltip-offset', converter: toInt({ default: 8 }), on: 'update', description: 'Gap in px between a badge and its tooltip.' }, { configKey: 'optionTooltipDelay', attribute: 'option-tooltip-delay', converter: toInt(), on: 'update', description: 'Delay in ms before an option tooltip appears (falls back to badgeTooltipDelay).' }, { configKey: 'optionTooltipOffset', attribute: 'option-tooltip-offset', converter: toInt(), on: 'update', description: 'Gap in px between an option and its tooltip.' }, // ── Booleans (default true) ────────────────────────────────────────────── { configKey: 'isMultipleEnabled', attribute: 'multiple', converter: toBool('default-true'), on: 'reinit', description: 'Allow selecting multiple options. When off, selecting one replaces the previous.' }, { configKey: 'isGroupsAllowed', attribute: 'allow-groups', converter: toBool('default-true'), on: 'reinit', description: 'Allow grouping options under group headers.' }, { configKey: 'isCheckboxesShown', attribute: 'show-checkboxes', converter: toBool('default-true'), on: 'reinit', description: 'Show a checkbox on each option.' }, { configKey: 'isActionsSticky', attribute: 'sticky-actions', converter: toBool('default-true'), on: 'update', description: 'Keep the action bar pinned while the list scrolls.' }, { configKey: 'isPlacementLocked', attribute: 'lock-placement', converter: toBool('default-true'), on: 'update', description: 'Keep the dropdown initial placement instead of flipping when it fits.' }, { configKey: 'isSearchEnabled', attribute: 'enable-search', converter: toBool('default-true'), on: 'reinit', description: 'Show the search input.' }, { configKey: 'isKeepOptionsOnSearch', attribute: 'keep-options-on-search', converter: toBool('default-true'), on: 'update', description: 'Keep already-selected options visible while filtering.' }, { configKey: 'shouldKeepSearchOnClose', attribute: 'should-keep-search-on-close', converter: toBool('default-true'), on: 'update', description: 'Preserve the search text after the dropdown closes.' }, { configKey: 'isSelectedPopoverEnabled', attribute: 'enable-selected-popover', converter: toBool('default-true'), on: 'update', description: 'Allow the selected-items popover to open (from the count/compact/\"+X more\" badge or the in-input counter). Turn off when you render your own selection UI, so those affordances become inert.' }, // ── Booleans (default false) ───────────────────────────────────────────── { configKey: 'isCloseOnSelect', attribute: 'close-on-select', converter: toBool('default-false'), on: 'update', description: 'Close the dropdown immediately after a selection.' }, { configKey: 'isAddNewAllowed', attribute: 'allow-add-new', converter: toBool('default-false'), on: 'reinit', description: 'Allow adding a new option from the search text.' }, { configKey: 'isCounterShown', attribute: 'show-counter', converter: toBool('default-false'), on: 'update', description: 'Show a selected-count indicator.' }, { configKey: 'isClearShown', attribute: 'show-clear', converter: toBool('default-false'), on: 'update', description: 'Show an inline clear (✕) button inside the input that wipes the whole selection. Appears only while something is selected and the control is enabled; clicking it clears the selection and any search text, fires `change`, and refocuses.' }, { configKey: 'isBadgeFullTitleShown', attribute: 'show-badge-full-title', converter: toBool('default-false'), on: 'update', description: 'Show the full title on badges instead of the short label.' }, { configKey: 'isVirtualScrollEnabled', attribute: 'enable-virtual-scroll', converter: toBool('default-false'), on: 'reinit', description: 'Force virtual scrolling on regardless of the threshold.' }, { configKey: 'isBadgeTooltipsEnabled', attribute: 'enable-badge-tooltips', converter: toBool('default-false'), on: 'update', description: 'Enable tooltips on badges.' }, { configKey: 'isOptionTooltipsEnabled', attribute: 'enable-option-tooltips', converter: toBool('default-false'), on: 'update', description: 'Enable tooltips on options.' }, { configKey: 'isOptionTooltipFollowCursor', attribute: 'option-tooltip-follow-cursor', converter: toBool('default-false'), on: 'update', description: 'Make option tooltips follow the pointer.' }, { configKey: 'isSearchModeToggleShown', attribute: 'show-search-mode-toggle', converter: toBool('default-false'), on: 'update', description: 'Show a clickable toggle in the phone fullscreen overlay search header that flips `search-mode` between `filter` and `navigate` live. Fullscreen-only; no effect in the floating presentation or when search is disabled.' }, // ── Special attributes ─────────────────────────────────────────────────── { configKey: 'initialValues', attribute: 'initial-values', converter: toInitialValues(), default: [], on: 'reinit', type: 'Array<string | number>', description: 'Values selected on first render. Accepts a JSON array (`[\"a\",\"b\"]`) or a bare CSV (`a,b,c`).' }, { configKey: 'showDebugInfo', attribute: 'show-debug-info', converter: toBool('default-false'), on: 'update', description: 'Render an in-component debug panel.', deprecated: 'Use per-instance logging (el.enableLogging()) instead.' }, // ── Complex property (data) ────────────────────────────────────────────── { configKey: 'options', converter: toObjectArray(), on: 'reinit', type: 'ReadonlyArray<Record<string, unknown>>', 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.' }, { configKey: 'optionsSource', attribute: 'data-options', converter: toText({ isNullable: true }), on: 'reinit', type: 'string', 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.' }, { configKey: 'optionsFormat', attribute: 'data-options-format', converter: toEnum(OPTIONS_FORMATS, { default: 'json' }), on: 'reinit', type: \"'json' | 'csv' | 'plain'\", description: 'How to parse the `data-options` attribute: `json` (a JSON array of objects or [value, label] tuples), `csv` (rows split on `data-options-row-splitter`, cells on `data-options-splitter`; the first row is a header — map columns via *-member), or `plain` (bare values split on both splitters -> [value, label] tuples, value === label). Default `json`.' }, { configKey: 'optionsSplitter', attribute: 'data-options-splitter', converter: toText({ default: ',' }), on: 'reinit', type: 'string', description: 'Field/cell delimiter for the `csv` and `plain` `data-options` formats. Default `,`. Escapes `\\\\t` `\\\\n` `\\\\r` are honoured (e.g. `data-options-splitter=\"\\\\t\"` for TSV). Ignored for `json`.' }, { configKey: 'optionsRowSplitter', attribute: 'data-options-row-splitter', converter: toText({ default: '\\n' }), on: 'reinit', type: 'string', description: 'Row/record delimiter for the `csv` and `plain` `data-options` formats. Default newline. Escapes honoured (e.g. `data-options-row-splitter=\";\"` for single-line data). Ignored for `json`.' }, { configKey: 'actionButtons', converter: toValue({ validate: (v): v is unknown[] => Array.isArray(v) }), on: 'reinit', type: 'Array<Record<string, unknown>>', description: 'Custom action buttons for the dropdown footer/header. Property-only; when unset the default Select-All / Clear buttons apply.' }, // ── Callbacks: data shape (structural → reinit) ────────────────────────── { configKey: 'getValueCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => string | number', description: 'Extract an option value (overrides valueMember).' }, { configKey: 'getPathCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => string', description: 'Extract a node tree path (enables tree mode; overrides pathMember).' }, { configKey: 'getGroupCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => string', description: 'Extract the group name from an option (overrides groupMember).' }, { configKey: 'getDisabledCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => boolean', description: 'Whether an option is disabled (overrides disabledMember).' }, { configKey: 'getIsSelectableCallback', converter: cb(), on: 'reinit', type: '(node: unknown) => boolean', description: 'Whether a tree node can be selected (overrides is-selectable-member).' }, { configKey: 'getSearchValueCallback', converter: cb(), on: 'reinit', type: '(item: unknown) => string', description: 'Text an option is searched against (overrides searchValueMember).' }, { configKey: 'searchCallback', converter: cb(), on: 'reinit', type: '(searchTerm: string, signal?: AbortSignal) => Promise<unknown[]>', description: 'Custom / async search; return the filtered options.' }, // ── Callbacks: display / render (cosmetic → update) ────────────────────── { configKey: 'getDisplayValueCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Compute the display label for an option (overrides displayValueMember).' }, { configKey: 'getBadgeDisplayCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Compute the text shown on an option badge.' }, { configKey: 'getBadgeClassCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | string[]', description: 'Extra CSS class(es) for an option badge.' }, { configKey: 'getIconCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Icon for an option (overrides iconMember).' }, { configKey: 'getSubtitleCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Subtitle for an option (overrides subtitleMember).' }, { configKey: 'getFullTitleCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Full title for an option (used by badges when show-badge-full-title is on).' }, { configKey: 'getCounterCallback', converter: cb(), on: 'update', type: '(count: number, moreCount?: number) => string', description: 'Render the selected-count label.' }, { configKey: 'getValueFormatCallback', converter: cb(), on: 'update', type: '(selectedValues: (string | number)[]) => string', description: 'Serialize the selected values for form submission.' }, { configKey: 'getBadgeTooltipCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | HTMLElement', description: 'Tooltip content for an option badge.' }, { configKey: 'getOptionTooltipCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | HTMLElement', description: 'Tooltip content for an option row.' }, { configKey: 'getRemoveButtonTooltipCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Tooltip text for a badge remove button.' }, { configKey: 'getSelectedItemClassCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | string[]', description: 'Extra CSS class(es) for a selected item.' }, { configKey: 'renderOptionContentCallback', converter: cb(), on: 'update', type: '(item: unknown, context: OptionContentRenderContext) => string | HTMLElement', description: 'Custom render for an option row; may return HTML or an element.' }, { configKey: 'renderBadgeContentCallback', converter: cb(), on: 'update', type: '(item: unknown, context: BadgeContentRenderContext) => string | HTMLElement', description: 'Custom render for a badge content (fills the built-in pill); may return HTML or an element.' }, { configKey: 'renderBadgeCallback', converter: cb(), on: 'update', type: '(item: unknown, context: BadgeContentRenderContext) => string | HTMLElement | null', description: 'Custom render for the WHOLE badge (main area), not just its content — return the entire pill/card. The component wraps it in `.ms__badge.ms__badge--custom` with `data-value` and delegates removal to any inner element with `data-action=\"remove\"` (or `.ms__badge-remove`). Return null/empty to fall back to the default pill for that item.' }, { configKey: 'renderGroupLabelContentCallback', converter: cb(), on: 'update', type: '(groupName: string) => string | HTMLElement', description: 'Customize a group label; may return an HTML string or element.' }, { configKey: 'renderSelectedContentCallback', converter: cb(), on: 'update', type: '(item: unknown) => string', description: 'Custom render for the whole selected area.' }, { configKey: 'renderSelectedItemContentCallback', converter: cb(), on: 'update', type: '(item: unknown) => string | HTMLElement', description: 'Custom render for one selected item.' }, { configKey: 'customStylesCallback', converter: cb(), on: 'update', type: '() => string', description: 'Returns a CSS string injected into the component via a replaceable style slot (§12.8).' }, // ── Callbacks: before-hooks (behavior-shaping) ─────────────────────────── { configKey: 'beforeSearchCallback', converter: cb(), on: 'update', type: '(searchTerm: string) => string | null', description: 'Runs before a search; return a rewritten term or null to veto.' }, { configKey: 'beforeSelectCallback', converter: cb(), on: 'update', type: '(option: unknown, selectedOptions: unknown[]) => boolean | string | void', description: 'Runs before selecting; return false to veto, or a string to veto and show it as a message.' }, { configKey: 'beforeDeselectCallback', converter: cb(), on: 'update', type: '(option: unknown, selectedOptions: unknown[]) => boolean | string | void', description: 'Runs before deselecting; return false to veto, or a string to veto and show it as a message.' }, { configKey: 'addNewCallback', converter: cb(), on: 'update', type: '(value: string) => unknown | Promise<unknown>', description: 'Create a new option from the typed text.' }, { configKey: 'keydownCallback', converter: cb(), on: 'update', type: '(context: MultiSelectKeydownContext) => boolean | void', description: 'Intercept keydown before built-in handling; return true to suppress the default. Gets the event, current state, and an imperative controller.' }, ]",
               "type": {
                 "text": "readonly InputDef[]"
               }
@@ -3982,6 +4047,44 @@
               },
               "description": "Dismiss the transient message shown by showMessage, if any."
             },
+            {
+              "kind": "method",
+              "name": "open",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Open the dropdown."
+            },
+            {
+              "kind": "method",
+              "name": "close",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Close the dropdown."
+            },
+            {
+              "kind": "method",
+              "name": "toggle",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Toggle the dropdown open/closed."
+            },
+            {
+              "kind": "field",
+              "name": "isOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the dropdown is currently open. Assigning opens/closes it."
+            },
             {
               "kind": "method",
               "name": "destroy",
@@ -4368,6 +4471,16 @@
               "attribute": "search-mode",
               "description": "Whether typing filters the list or navigates it."
             },
+            {
+              "kind": "field",
+              "name": "overlayGroup",
+              "privacy": "public",
+              "type": {
+                "text": "string | null"
+              },
+              "attribute": "overlay-group",
+              "description": "Scope the \"one overlay open at a time\" coordination to a named group. Overlays (multiselects, datepickers, external popovers) sharing a group dismiss each other when one opens; different groups are independent. Unset = the default (ungrouped) group."
+            },
             {
               "kind": "field",
               "name": "actionsLayout",
@@ -4725,6 +4838,16 @@
               "attribute": "show-counter",
               "description": "Show a selected-count indicator."
             },
+            {
+              "kind": "field",
+              "name": "isClearShown",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "attribute": "show-clear",
+              "description": "Show an inline clear (✕) button inside the input that wipes the whole selection. Appears only while something is selected and the control is enabled; clicking it clears the selection and any search text, fires `change`, and refocuses."
+            },
             {
               "kind": "field",
               "name": "isBadgeFullTitleShown",
@@ -5437,6 +5560,14 @@
               "default": "'filter'",
               "description": "Whether typing filters the list or navigates it."
             },
+            {
+              "name": "overlay-group",
+              "fieldName": "overlayGroup",
+              "type": {
+                "text": "string | null"
+              },
+              "description": "Scope the \"one overlay open at a time\" coordination to a named group. Overlays (multiselects, datepickers, external popovers) sharing a group dismiss each other when one opens; different groups are independent. Unset = the default (ungrouped) group."
+            },
             {
               "name": "actions-layout",
               "fieldName": "actionsLayout",
@@ -5725,6 +5856,14 @@
               },
               "description": "Show a selected-count indicator."
             },
+            {
+              "name": "show-clear",
+              "fieldName": "isClearShown",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Show an inline clear (✕) button inside the input that wipes the whole selection. Appears only while something is selected and the control is enabled; clicking it clears the selection and any search text, fires `change`, and refocuses."
+            },
             {
               "name": "show-badge-full-title",
               "fieldName": "isBadgeFullTitleShown",