@keenmate/web-multiselect 1.12.0-rc03 → 1.12.0-rc05

package/README.md

@@ -21,11 +21,25 @@ Reads `--base-*` variables from the page if [`@keenmate/theme-designer`](https:/
 - Custom rendering callbacks for options, badges, and group headers.
 - Form integration via standard hidden inputs (FormData-compatible).
 
-## What's new
+## What's New in v1.12.0-rc05
 
-**v1.12.0-rc03** — Two real bug fixes. (1) Declarative `<option>` / `<optgroup>` children now render correctly without needing `value-member` / `display-value-member` / `group-member` attributes — previously every row rendered as `[N/A]`. (2) `select`, `deselect`, and `change` events are now dispatched with `bubbles: true, composed: true`, so Svelte 5 `onchange={fn}`, React `onChange`, Vue `@change`, and any other framework using delegated event routing work without reaching for the legacy `on:` directive. **Behavior change:** delegated form-level `change` listeners will now also receive our event — filter by `e.target.tagName === 'WEB-MULTISELECT'` if your form library extracts state from every `change`. See [CHANGELOG.md](./CHANGELOG.md) for details.
+> ⚠️ **Breaking change — event-handler rename, no aliases.** The fire-and-forget notification callbacks are renamed to `on*` with **no backward-compatible aliases**: `selectCallback` → `onSelect`, `deselectCallback` → `onDeselect`, `changeCallback` → `onChange`, and on `ActionButton`, `isVisibleCallback` / `isDisabledCallback` → `getIsVisibleCallback` / `getIsDisabledCallback`. If you assign these as element properties or config keys, **rename them or your handlers silently stop firing**. The `select` / `deselect` / `change` **DOM events are unchanged**, so `addEventListener(...)` consumers are unaffected. Full rationale in the first bullet below.
 
-**v1.12.0-rc02** — Badge tooltips now theme correctly when portaled (real dark-mode contrast fix); FOUC-prevention rule renamed to match the actual tag; README split into slim landing page + `docs/` (usage, theming, examples, accessibility). See [CHANGELOG.md](./CHANGELOG.md) for details.
+- **Events — fire-and-forget callbacks renamed to `on*` (breaking)** — `selectCallback` / `deselectCallback` / `changeCallback` are now `onSelect` / `onDeselect` / `onChange`, and on `ActionButton` the predicate callbacks become `getIsVisibleCallback` / `getIsDisabledCallback` while `onClick` keeps its name. The rule is simple: a function whose return value the component ignores is an *event* and takes the `on*` shape; functions whose return value is consumed stay `get*Callback` / `before*Callback`. The bubbling `select` / `deselect` / `change` DOM events are unchanged — the `on*` properties are just their JS-property twins. There are no deprecated aliases, so update `el.selectCallback` → `el.onSelect` (and the matching config keys); `addEventListener('select' | 'deselect' | 'change', …)` is unaffected.
+- **Selection — new `beforeSelectCallback` / `beforeDeselectCallback` interceptors** — veto a selection or deselection before it happens by returning `false`; each receives the option being toggled plus the current selection. The veto is silent — a blocked action mutates no state and fires no event, so your handler owns any feedback. The deselect veto is enforced across *every* interactive removal path (dropdown toggle, badge `×`, selected-items popover, and the "remove hidden" badge) by routing them through a single funnel, so no affordance can bypass it; programmatic `setSelected()` and the Select-All / Clear-All buttons deliberately skip it. Typical uses: mutually-exclusive options, or a required item that can't be removed.
+- **Dropdown options — hover tooltips, independently configurable** — option rows can now show a hover tooltip via `enable-option-tooltips`, built on the same Floating-UI `Tooltip` engine as the badge and action tooltips (show/hide delays, plus re-attachment as virtual-scrolled rows recycle into view). Default content is the option's display value with its subtitle on a second line; override per option with `getOptionTooltipCallback`. Unlike the badge tooltips they share an engine with, option tooltips are fully independent: `option-tooltip-placement` defaults to `top-start` so the tooltip anchors to a wide row's start edge instead of centering in the middle of a 1920px-wide row, `option-tooltip-follow-cursor` makes it track the pointer, and a dedicated `.ms__option-tooltip` class plus `--ms-option-tooltip-*` variables (each defaulting to the shared `--ms-tooltip-*` surface) let you restyle them separately. Demonstrated on the new `examples-tooltips.html`.
+- **Action buttons — position, rows, and alignment** — the action-buttons block can sit at the `bottom` of the dropdown as a sticky footer (`actions-position`), buttons can be arranged across multiple stacked rows via a per-button `row` property (row 1 always at the panel's outer edge, higher rows stacking inward toward the options list — so `column-reverse` keeps row 1 at the bottom for the footer case), and `actions-align` controls horizontal arrangement (`stretch` default, plus `left` / `right` / `center` / `space-between`). Internally `.ms__actions` became a vertical stack of `.ms__actions-row` lines. All additive and backward compatible — no `row` means a single row, and `stretch` preserves the previous full-width buttons.
+- **Action buttons — smarter built-in defaults** — the built-in `select-all` and `clear-all` actions now manage their own disabled state: Select All disables once every selectable option is chosen, and Clear All disables while nothing is selected. This applies only when you haven't set an explicit static `isDisabled` or a `getIsDisabledCallback` (precedence: dynamic callback › static `isDisabled` › built-in default), so existing custom action configs are untouched.
+- **Single-select — dropdown no longer reopens with a stale filter** — the single-select input doubles as label display and search box; reopening used to blank the visible text while leaving the list filtered by the previous search, so the box and the list silently disagreed. `open()` now mirrors the kept search term back into the box, keeping the visible input and the filtered results in sync (honoring `should-keep-search-on-close`).
+- **Async search — dropdown stops jumping between empty and loading states** — the "No data" empty state and the loading spinner now share a min-height (`--ms-state-min-height`, a new themable variable), so the panel keeps a stable footprint instead of resizing as an async search swaps one block for the other.
+- **Docs — new live demo page for events & interceptors** — `examples-events-callbacks.html` shows the DOM events, the `on*` property twin firing in parallel, and interactive veto demos for the new interceptors.
+
+## What's New in v1.12.0-rc04
+
+- **Placeholders — context-aware wording for pickers and empty cascades** — The input used to show `"Search..."` unconditionally, even when search was off or there was nothing to pick. Two new attributes fix that. `select-placeholder` (default `"Pick an option..."`) is shown when the input isn't a usable search box — `enable-search="false"`, or `search-input-mode="readonly"`/`"hidden"` — so a non-searchable picker stops mislabeling itself. `no-data-placeholder` is an opt-in string shown when the option list is empty, letting users see there's nothing to choose without opening the dropdown; it targets cascade multiselects whose parent isn't resolved yet, and stays unset by default so async-loaded selects don't flash an empty-state before their data lands. Placeholder resolution is now recomputed on live updates too, so changing these attributes, the search mode, or the option list updates the visible text on the fly. **Behavior change:** search-disabled instances without a custom placeholder now read `"Pick an option..."` — set `select-placeholder="Search..."` to keep the old text.
+- **setAttributes() — batch attribute updates in a single render** — Setting attributes one at a time triggered a full re-render per call. The new `setAttributes(attrs)` method on `<web-multiselect>` applies a whole map of attributes in one in-place update (or a single reinit at most, if any change is structural). Keys are kebab-case attribute names, exactly like `setAttribute`; a value of `null`/`undefined`/`false` removes the attribute and `true` sets it to `""`. It's particularly handy for i18n language switches that swap several placeholder strings at once without flicker.
+- **search-debounce — coalesce async search into one request** — A new `search-debounce` attribute (milliseconds, default `0`) debounces the async `searchCallback` so a burst of keystrokes collapses into a single request instead of one per character. Each keystroke resets the timer, and it applies to the async `searchCallback` path only — local in-memory filtering stays instant. The existing stale-result guard (results applied only if the term still matches) remains as a second line of defense against out-of-order responses. The examples page §8 now ships a "Debounced Search" demo with a live keystrokes-vs-API-calls counter that makes the coalescing obvious.
+- **searchCallback AbortSignal — cancel superseded in-flight requests** — `searchCallback` now receives an `AbortSignal` as its second argument: `(searchTerm, signal) => Promise<options[]>`. When a newer search supersedes an in-flight one — or the term drops below `min-search-length`, or the component is destroyed — the previous request's signal is aborted; forward it into `fetch(url, { signal })` to actually cancel the network call. It's backward compatible: the argument is optional, and existing callbacks that ignore it keep working with their stale results discarded as before. Aborted or superseded responses never overwrite the live filtered options.
 
 > ⚠️ **Security notice:** This component intentionally allows raw HTML in rendering callbacks to give developers full control over content display. If you display user-generated content, you must sanitize it yourself. See [docs/examples.md → HTML Injection (XSS) notice](./docs/examples.md#html-injection-xss-notice) for the complete list of affected callbacks.
 
@@ -106,8 +120,29 @@ npm run build
 
 # Create package tarball
 npm run package
+
+# Run tests
+npm run test:unit   # Vitest (happy-dom) — fast logic checks
+npm run test:e2e    # Playwright (browser) — interaction/visual
+npm test            # both
 ```
 
+## Code structure
+
+Follows the BlissFramework four-layer web-component layout:
+
+| Layer | File | Role |
+|-------|------|------|
+| Element | `src/web-component.ts` | `MultiSelectElement` — custom-element I/O wrapper, `ATTRIBUTE_TABLE`-driven |
+| Logic | `src/multiselect.ts` | `WebMultiSelect<T>` — framework-agnostic core |
+| Service | `src/tooltip.ts`, `src/virtual-scroll.ts` | single-purpose helpers (`Tooltip`, `VirtualScroll`) |
+| Side | `src/types.ts`, `src/logger.ts`, `src/vendor/` | types, logging, vendored deps |
+
+Two deviations from the canonical shape, both intentional:
+
+- **`MultiSelectElement extends BaseElement`, not `HTMLElement` directly.** `BaseElement` is a local `const` resolving to `HTMLElement` in the browser and to a stub class under SSR (`typeof HTMLElement === 'undefined'`), so importing the module in Node doesn't throw. A literal `grep "extends HTMLElement"` structure check will not match here by design.
+- **`src/vite-env.d.ts`** is a standard Vite ambient-types file, not part of the four-layer model.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/component-variables.manifest.json

@@ -241,6 +241,7 @@
     { "name": "ms-checkbox-checked-bg-hover", "category": "checkbox", "usage": "Checked checkbox hover background" },
     { "name": "ms-checkbox-checked-border-color-hover", "category": "checkbox", "usage": "Checked checkbox hover border" },
 
+    { "name": "ms-state-min-height", "category": "empty", "usage": "Shared min-height for the empty and loading states so the dropdown doesn't resize when swapping between them" },
     { "name": "ms-empty-padding", "category": "empty", "usage": "Empty state padding" },
     { "name": "ms-empty-font-size", "category": "empty", "usage": "Empty state font size" },
     { "name": "ms-empty-color", "category": "empty", "usage": "Empty state text color" },

package/dist/index.d.ts

@@ -11,6 +11,13 @@ declare interface ActionButton<T = any> {
     text: string;
     /** Optional CSS class(es) to add to the button */
     cssClass?: string;
+    /**
+     * 1-based row this button belongs to (default `1`). Buttons sharing a `row` render on the same
+     * horizontal line; different values stack into multiple rows. Row 1 sits at the panel's outer edge
+     * and higher rows stack inward toward the options list — so with `actions-position="top"` row 1 is
+     * the topmost line, and with `actions-position="bottom"` row 1 is the bottommost line.
+     */
+    row?: number;
     /** Optional tooltip text */
     tooltip?: string;
     /** Static visibility - set to false to hide button */
@@ -20,9 +27,9 @@ declare interface ActionButton<T = any> {
     /** Custom click handler (required for 'custom' action) */
     onClick?: (multiselect: any) => void | Promise<void>;
     /** Dynamic visibility callback - return false to hide button (takes priority over isVisible) */
-    isVisibleCallback?: (multiselect: any) => boolean;
+    getIsVisibleCallback?: (multiselect: any) => boolean;
     /** Dynamic disabled state callback - return true to disable button (takes priority over isDisabled) */
-    isDisabledCallback?: (multiselect: any) => boolean;
+    getIsDisabledCallback?: (multiselect: any) => boolean;
     /** Dynamic text callback - return button text (takes priority over text) */
     getTextCallback?: (multiselect: any) => string;
     /** Dynamic CSS class callback - return class name(s) (takes priority over cssClass) */
@@ -31,6 +38,9 @@ declare interface ActionButton<T = any> {
     getTooltipCallback?: (multiselect: any) => string;
 }
 
+/** Horizontal arrangement of buttons within an action row. `stretch` = full-width (default). */
+declare type ActionsAlign = 'stretch' | 'left' | 'right' | 'center' | 'space-between';
+
 /**
  * Layout mode for action buttons container
  * - 'nowrap': Buttons stay in single row (default)
@@ -38,6 +48,9 @@ declare interface ActionButton<T = any> {
  */
 declare type ActionsLayout = 'nowrap' | 'wrap';
 
+/** Where the action-buttons block sits in the dropdown panel. */
+declare type ActionsPosition = 'top' | 'bottom';
+
 /**
  * Context provided to renderBadgeContentCallback
  */
@@ -196,8 +209,20 @@ declare interface MultiSelectConfig<T = any> {
     checkboxAlign?: 'top' | 'center' | 'bottom';
     /** Hint text shown above the input while the dropdown is open. */
     searchHint?: string;
-    /** Placeholder text for the search input */
+    /** Placeholder text for the search input (shown while search is usable) */
     searchPlaceholder?: string;
+    /**
+     * Placeholder shown when search is disabled (input acts as a picker rather than a search box).
+     * Applies when `isSearchEnabled` is false or `searchInputMode` is 'readonly'/'hidden'.
+     * Default: "Pick an option..."
+     */
+    selectPlaceholder?: string;
+    /**
+     * Placeholder shown when there are no options to choose from (e.g. an unresolved cascade parent).
+     * Opt-in: when unset, the normal search/select placeholder is used even with an empty list.
+     * Lets users see there is no data without opening the dropdown.
+     */
+    noDataPlaceholder?: string;
     /** Minimum width for the dropdown (e.g., '20rem', '300px') */
     dropdownMinWidth?: string | null;
     /** Maximum width for the dropdown (e.g., '40rem', '500px') */
@@ -220,12 +245,23 @@ declare interface MultiSelectConfig<T = any> {
     searchMode?: SearchMode;
     /** Layout mode for action buttons: 'nowrap' (default) or 'wrap' for multi-row */
     actionsLayout?: ActionsLayout;
+    /** Where the action-buttons block sits in the dropdown: 'top' (default) or 'bottom' (sticky footer). */
+    actionsPosition?: ActionsPosition;
+    /** Horizontal arrangement of buttons within a row: 'stretch' (default, full-width), 'left', 'right', 'center', or 'space-between'. */
+    actionsAlign?: ActionsAlign;
     /** Auto-switch from badges to count when threshold is exceeded */
     badgesThreshold?: number | null;
     /** Maximum number of badges to show in partial mode (used with thresholdMode='partial') */
     badgesMaxVisible?: number | null;
     /** Minimum search length before loading data */
     minSearchLength?: number;
+    /**
+     * Debounce delay in milliseconds before the async `searchCallback` is invoked.
+     * Each keystroke resets the timer, so only the last input in a burst fires a request.
+     * Applies to the async `searchCallback` path only — local in-memory filtering stays instant.
+     * Default: 0 (no debounce — callback runs on every keystroke).
+     */
+    searchDebounce?: number;
     /** Minimum items before virtual scroll activates (default: 100) */
     virtualScrollThreshold?: number;
     /** Fixed height for each option in pixels (required for virtual scroll, default: 50) */
@@ -236,16 +272,38 @@ declare interface MultiSelectConfig<T = any> {
     virtualScrollBuffer?: number;
     /** Pre-process search term before calling searchCallback. Return null to prevent search. Use for accent removal, validation, etc. */
     beforeSearchCallback?: ((searchTerm: string) => string | null) | null;
-    /** Async function to load data: (searchTerm) => Promise<options[]> */
-    searchCallback?: ((searchTerm: string) => Promise<T[]>) | null;
+    /**
+     * Interceptor: runs before an option is selected via user interaction.
+     * Receives the option about to be added and the current selection (before the change).
+     * Return `false` to block the selection; return `true`/`undefined` to allow.
+     * Silent — a blocked action fires no event. Bypassed by programmatic `setSelected`
+     * and the Select-All action button.
+     */
+    beforeSelectCallback?: ((option: T, selectedOptions: T[]) => boolean | void) | null;
+    /**
+     * Interceptor: runs before an option is deselected via user interaction — the dropdown
+     * option toggle, a badge's remove (×) button, the selected-items popover's remove button,
+     * and the "remove hidden" badge (checked per item). Receives the option about to be
+     * removed and the current selection (before the change). Return `false` to block the
+     * deselection; return `true`/`undefined` to allow. Silent — a blocked action fires no
+     * event. Bypassed by programmatic `setSelected` and the Clear-All action button.
+     */
+    beforeDeselectCallback?: ((option: T, selectedOptions: T[]) => boolean | void) | null;
+    /**
+     * Async function to load data: `(searchTerm, signal) => Promise<options[]>`.
+     * The optional second argument is an `AbortSignal` that fires when a newer search
+     * supersedes this one (or the component is destroyed). Wire it into your `fetch`
+     * to cancel the in-flight request; ignoring it is fine — stale results are discarded.
+     */
+    searchCallback?: ((searchTerm: string, signal?: AbortSignal) => Promise<T[]>) | null;
     /** Callback to add a new option when isAddNewAllowed is true */
     addNewCallback?: ((value: string) => T | Promise<T>) | null;
-    /** Callback when an option is selected */
-    selectCallback?: ((option: T) => void) | null;
-    /** Callback when an option is deselected */
-    deselectCallback?: ((option: T) => void) | null;
-    /** Callback when selection changes */
-    changeCallback?: ((selectedOptions: T[]) => void) | null;
+    /** Event handler: an option was selected (fire-and-forget; return value ignored). Mirrors the bubbling `select` CustomEvent on the element. */
+    onSelect?: ((option: T) => void) | null;
+    /** Event handler: an option was deselected (fire-and-forget). Mirrors the bubbling `deselect` CustomEvent on the element. */
+    onDeselect?: ((option: T) => void) | null;
+    /** Event handler: the selection set changed (fire-and-forget). Mirrors the bubbling `change` CustomEvent on the element. */
+    onChange?: ((selectedOptions: T[]) => void) | null;
     /** Callback to format count badge text (for i18n/pluralization). When moreCount is provided, it's for the "+X more" badge in partial mode. */
     getCounterCallback?: ((count: number, moreCount?: number) => string) | null;
     /** Enable tooltips on selected item badges (internal: isBadgeTooltipsEnabled) */
@@ -262,6 +320,18 @@ declare interface MultiSelectConfig<T = any> {
     badgeTooltipDelay?: number;
     /** Offset distance for tooltip in pixels */
     badgeTooltipOffset?: number;
+    /** Enable tooltips on dropdown options (internal: isOptionTooltipsEnabled) */
+    isOptionTooltipsEnabled?: boolean;
+    /** Callback to generate custom tooltip content for a dropdown option. Default: display value, plus subtitle on the next line when present. */
+    getOptionTooltipCallback?: ((item: T) => string | HTMLElement) | null;
+    /** Option tooltip placement. Default `'top-start'` (anchored to the row's start edge, so it doesn't center on a full-width row). Use `'left'`/`'right'` (start/end side) for a narrow multiselect. */
+    optionTooltipPlacement?: Placement;
+    /** Delay before showing an option tooltip (ms). Falls back to `badgeTooltipDelay`, then `100`. */
+    optionTooltipDelay?: number;
+    /** Offset distance for an option tooltip (px). Falls back to `badgeTooltipOffset`, then `8`. */
+    optionTooltipOffset?: number;
+    /** Anchor the option tooltip to the mouse pointer and follow it across the row (best for full-width rows). Default `false`. */
+    isOptionTooltipFollowCursor?: boolean;
     /** Container element for dropdown/hint/popover (for Shadow DOM support) */
     container?: HTMLElement | null;
     /** Host element for appending hidden inputs (for form integration with shadow DOM) */
@@ -296,6 +366,7 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     private _getDisabledCallback?;
     private _getValueFormatCallback?;
     private _getBadgeTooltipCallback?;
+    private _getOptionTooltipCallback?;
     private _getRemoveButtonTooltipCallback?;
     private _renderOptionContentCallback?;
     private _renderBadgeContentCallback?;
@@ -304,12 +375,17 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     private _renderSelectedContentCallback?;
     private _getCounterCallback?;
     private _actionButtons?;
+    private _batchDepth;
+    private _batchPartial;
+    private _batchNeedsReinit;
     private _beforeSearchCallback?;
+    private _beforeSelectCallback?;
+    private _beforeDeselectCallback?;
     private _searchCallback?;
     private _addNewCallback?;
-    private _selectCallback?;
-    private _deselectCallback?;
-    private _changeCallback?;
+    private _onSelect?;
+    private _onDeselect?;
+    private _onChange?;
     static get observedAttributes(): string[];
     constructor();
     /**
@@ -323,6 +399,20 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Set several attributes in one in-place update — a single re-render instead of one per
+     * attribute (and a single reinit at most if any change is structural). Keys are attribute
+     * names in kebab-case, exactly as `setAttribute`. A value of `null`/`undefined`/`false`
+     * removes the attribute; `true` sets it to an empty string; anything else is stringified.
+     *
+     * @example
+     *   el.setAttributes({
+     *     'search-placeholder': t('search'),
+     *     'select-placeholder': t('pick'),
+     *     'no-data-placeholder': t('noData'),
+     *   });
+     */
+    setAttributes(attrs: Record<string, string | number | boolean | null | undefined>): void;
     private render;
     private renderDebugInfo;
     private updateDebugInfo;
@@ -407,6 +497,18 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     get checkboxAlign(): string | null;
     set enableBadgeTooltips(value: boolean);
     get enableBadgeTooltips(): boolean;
+    set enableOptionTooltips(value: boolean);
+    get enableOptionTooltips(): boolean;
+    set getOptionTooltipCallback(callback: ((item: T) => string | HTMLElement) | undefined);
+    get getOptionTooltipCallback(): ((item: T) => string | HTMLElement) | undefined;
+    set optionTooltipPlacement(value: string | null);
+    get optionTooltipPlacement(): string | null;
+    set optionTooltipFollowCursor(value: boolean);
+    get optionTooltipFollowCursor(): boolean;
+    set actionsPosition(value: string | null);
+    get actionsPosition(): string | null;
+    set actionsAlign(value: string | null);
+    get actionsAlign(): string | null;
     set badgeTooltipPlacement(value: string | null);
     get badgeTooltipPlacement(): string | null;
     set getBadgeTooltipCallback(callback: ((item: T) => string | HTMLElement) | undefined);
@@ -419,16 +521,20 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     get getCounterCallback(): ((count: number, moreCount?: number) => string) | undefined;
     get beforeSearchCallback(): ((searchTerm: string) => string | null) | undefined;
     set beforeSearchCallback(callback: ((searchTerm: string) => string | null) | undefined);
-    get searchCallback(): ((searchTerm: string) => Promise<T[]>) | undefined;
-    set searchCallback(callback: ((searchTerm: string) => Promise<T[]>) | undefined);
+    get beforeSelectCallback(): ((option: T, selectedOptions: T[]) => boolean | void) | undefined;
+    set beforeSelectCallback(callback: ((option: T, selectedOptions: T[]) => boolean | void) | undefined);
+    get beforeDeselectCallback(): ((option: T, selectedOptions: T[]) => boolean | void) | undefined;
+    set beforeDeselectCallback(callback: ((option: T, selectedOptions: T[]) => boolean | void) | undefined);
+    get searchCallback(): ((searchTerm: string, signal?: AbortSignal) => Promise<T[]>) | undefined;
+    set searchCallback(callback: ((searchTerm: string, signal?: AbortSignal) => Promise<T[]>) | undefined);
     get addNewCallback(): ((value: string) => T | Promise<T>) | undefined;
     set addNewCallback(callback: ((value: string) => T | Promise<T>) | undefined);
-    get selectCallback(): ((option: T) => void) | undefined;
-    set selectCallback(callback: ((option: T) => void) | undefined);
-    get deselectCallback(): ((option: T) => void) | undefined;
-    set deselectCallback(callback: ((option: T) => void) | undefined);
-    get changeCallback(): ((selectedOptions: T[]) => void) | undefined;
-    set changeCallback(callback: ((selectedOptions: T[]) => void) | undefined);
+    get onSelect(): ((option: T) => void) | undefined;
+    set onSelect(callback: ((option: T) => void) | undefined);
+    get onDeselect(): ((option: T) => void) | undefined;
+    set onDeselect(callback: ((option: T) => void) | undefined);
+    get onChange(): ((selectedOptions: T[]) => void) | undefined;
+    set onChange(callback: ((selectedOptions: T[]) => void) | undefined);
     get actionButtons(): any[] | undefined;
     set actionButtons(value: any[] | undefined);
     get selectedValue(): string | number | (string | number)[] | null;
@@ -478,11 +584,11 @@ export declare interface MultiSelectOption {
  */
 export declare interface MultiSelectOptions extends MultiSelectConfig<MultiSelectOption> {
     options?: MultiSelectOption[];
-    searchCallback?: ((searchTerm: string) => Promise<MultiSelectOption[]>) | null;
+    searchCallback?: ((searchTerm: string, signal?: AbortSignal) => Promise<MultiSelectOption[]>) | null;
     addNewCallback?: ((value: string) => MultiSelectOption | Promise<MultiSelectOption>) | null;
-    selectCallback?: ((option: MultiSelectOption) => void) | null;
-    deselectCallback?: ((option: MultiSelectOption) => void) | null;
-    changeCallback?: ((selectedOptions: MultiSelectOption[]) => void) | null;
+    onSelect?: ((option: MultiSelectOption) => void) | null;
+    onDeselect?: ((option: MultiSelectOption) => void) | null;
+    onChange?: ((selectedOptions: MultiSelectOption[]) => void) | null;
 }
 
 /**
@@ -548,6 +654,8 @@ export declare class WebMultiSelect<T = any> {
     private matchingIndices;
     private searchTerm;
     private isLoading;
+    private searchDebounceTimer?;
+    private searchAbortController?;
     private showSelectedPopover;
     private selectedPopoverPlacement;
     private dropdownPlacement;
@@ -620,13 +728,43 @@ export declare class WebMultiSelect<T = any> {
      * Render the Select All / Clear All / custom action buttons row.
      * Returns the empty string if multiple-select is off or no buttons are configured.
      */
+    /**
+     * Default enabled/disabled state for the built-in actions, applied only when the consumer hasn't
+     * set an explicit `isDisabled` / `getIsDisabledCallback`:
+     * - `select-all` is disabled when it would add nothing (every selectable, non-disabled filtered
+     *   option is already selected — this also covers an empty list).
+     * - `clear-all` is disabled when nothing is selected.
+     */
+    private getBuiltInActionDisabled;
     private renderActionsHTML;
     private renderOption;
     private highlightMatch;
     private groupOptions;
+    /** Whether the input currently functions as a usable search field (drives placeholder wording). */
+    private get isSearchUsable();
+    /**
+     * Resolve the closed-state input placeholder for the current data/search state.
+     * Priority: explicit no-data placeholder (when the list is empty) → "pick" prompt when
+     * search is unusable → the search placeholder.
+     */
+    private getPlaceholderText;
     private renderBadges;
     private attachEvents;
     private handleSearch;
+    /** Abort the search request currently in flight, if any. The aborted request's results
+     *  are then ignored (and the consumer's `searchCallback` can short-circuit its fetch via
+     *  the `AbortSignal` it was handed). */
+    private abortInFlightSearch;
+    /**
+     * Invoke the async `searchCallback` and apply its results. Split out of `handleSearch`
+     * so it can be called immediately or after the debounce timer.
+     *
+     * Any request still in flight is aborted before a new one starts, so a slow earlier
+     * request can't overwrite a newer one — and consumers that wire the passed `AbortSignal`
+     * into their fetch get the request actually cancelled, not just ignored. The
+     * `aborted` / `searchTerm === value` guards drop superseded or out-of-order responses.
+     */
+    private performAsyncSearch;
     private handleKeydown;
     private handleDropdownClick;
     private handleBadgeClick;
@@ -646,6 +784,23 @@ export declare class WebMultiSelect<T = any> {
     private focusPreviousMatch;
     private scrollToFocused;
     private toggleOption;
+    /**
+     * The single funnel for an interactive (user-initiated) selection. Consults
+     * `beforeSelectCallback` and only mutates state if allowed, so the veto can
+     * never be bypassed by a new UI entry point. Programmatic `setSelected` and
+     * the Select-All button deliberately do not route through here.
+     * Returns true if the option was selected, false if the veto blocked it.
+     */
+    private interactiveSelect;
+    /**
+     * The single funnel for an interactive (user-initiated) deselection. Every
+     * removal affordance — dropdown toggle, badge × button, selected-items
+     * popover × button, and the "remove hidden" badge — routes through here so
+     * the `beforeDeselectCallback` veto applies uniformly. Programmatic
+     * `setSelected` and the Clear-All button deliberately bypass it.
+     * Returns true if the option was deselected, false if the veto blocked it.
+     */
+    private interactiveDeselect;
     private handleAddNew;
     private selectOption;
     private deselectOption;
@@ -654,7 +809,7 @@ export declare class WebMultiSelect<T = any> {
     /**
      * Re-render and fire callbacks after a selection state change.
      * `added` / `removed` drive per-item select/deselect callbacks.
-     * `changeCallback` fires once if anything actually changed.
+     * `onChange` fires once if anything actually changed.
      */
     private commit;
     private open;
@@ -738,6 +893,20 @@ export declare class WebMultiSelect<T = any> {
     /** Build the remove-button tooltip text (callback > format string with {0} > "Remove {name}"). */
     private buildRemoveButtonTooltipText;
     private attachBadgeTooltips;
+    /** Build the option tooltip content (callback overrides; default = displayValue + optional subtitle on next line). */
+    private buildOptionTooltipContent;
+    /**
+     * Attach hover tooltips to the currently rendered dropdown options. Prunes existing option
+     * tooltips first, so it's safe to call on every render and on every virtual-scroll range change
+     * (where option DOM is recycled). Each option resolves its source object via `data-index` into
+     * `filteredOptions`, the same global index `renderOption` was given.
+     */
+    private attachOptionTooltips;
+    /**
+     * Destroy only the option tooltips (prefixed `option-`). Called before re-rendering or
+     * recycling the options list so per-option tooltip state doesn't leak.
+     */
+    private destroyAllOptionTooltips;
     private attachActionButtonTooltips;
     /**
      * Destroy only the action-button tooltips. Called from `renderDropdown`/`renderDropdownVirtual`