@keenmate/web-multiselect 1.12.0-rc04 → 1.12.0-rc06

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
  */
@@ -107,6 +120,31 @@ export declare const interactionLogger: any;
  */
 export declare const LOGGING_CATEGORIES: string[];
 
+declare interface LTreeNode<T> {
+    treeId: string;
+    id: NodeId;
+    /** Materialized dot-path, e.g. "1.2.3". */
+    path: string;
+    /** This node's own segment relative to its parent. */
+    pathSegment: string;
+    parentPath: string | null | undefined;
+    /** Depth in the tree (1-based; root children are level 1). */
+    level: number | null | undefined;
+    /** Children keyed by prefixed segment (see `segmentPrefix` in ltree.ts). */
+    children: Record<string, LTreeNode<T>>;
+    hasChildren: boolean;
+    /**
+     * Whether this node may be selected. Defaults to `true`; set `false` (via
+     * `isSelectableMember`/`getIsSelectableCallback`) to make a node non-interactive
+     * — it renders normally (no grey/disabled styling) but has no checkbox, is
+     * skipped by keyboard focus, and cannot be toggled or selected by Select-All.
+     * This is distinct from `disabled` (which greys the row out).
+     */
+    isSelectable: boolean;
+    /** The original option object this node was built from. */
+    data: T | null | undefined;
+}
+
 /**
  * Generic configuration options for the MultiSelect component
  * @template T The type of data items
@@ -124,6 +162,15 @@ declare interface MultiSelectConfig<T = any> {
     getDisplayValueCallback?: (item: T) => string;
     /** Callback to customize badge display text (defaults to display value if not provided) */
     getBadgeDisplayCallback?: (item: T) => string;
+    /**
+     * Member property name for a "full title" — a fully-qualified label that ships with the
+     * data (e.g. a breadcrumb like "Fruit / Pome fruit / Apple"). It is never computed by the
+     * component. When `isBadgeFullTitleShown` is on, badges display this instead of the display
+     * value (falling back to the display value when an option has none).
+     */
+    fullTitleMember?: string;
+    /** Callback to extract the full title from an item (takes precedence over `fullTitleMember`). */
+    getFullTitleCallback?: (item: T) => string;
     /** Callback to add custom CSS classes to badges - return string or array of class names */
     getBadgeClassCallback?: (item: T) => string | string[];
     /** Callback to inject custom CSS into Shadow DOM - return CSS string for styling custom classes */
@@ -140,6 +187,55 @@ declare interface MultiSelectConfig<T = any> {
     subtitleMember?: string;
     /** Callback to extract subtitle from item */
     getSubtitleCallback?: (item: T) => string;
+    /**
+     * Enable tree mode: options are rendered as a hierarchy, indented by depth.
+     * Auto-enabled when a path source (`pathMember`/`getPathCallback`) is set;
+     * pass `false` to force it off. The tree is always fully expanded — there is
+     * no collapse (use @keenmate/web-treeview if you need expand/collapse).
+     */
+    isTreeEnabled?: boolean;
+    /** Member property name holding each option's materialized dot-path (e.g. "1.2.3"). */
+    pathMember?: string;
+    /** Callback returning an option's materialized dot-path (takes precedence over pathMember). */
+    getPathCallback?: (item: T) => string;
+    /** Member holding an option's parent path (otherwise derived from its path). */
+    parentPathMember?: string;
+    /** Member holding an option's depth/level (otherwise derived from its path). */
+    levelMember?: string;
+    /** Member holding a precomputed hasChildren flag (otherwise derived from the tree). */
+    hasChildrenMember?: string;
+    /** Path separator for tree paths. Default: "." */
+    treePathSeparator?: string;
+    /**
+     * Member holding a per-option `isSelectable` flag for tree mode. A node with a
+     * falsy value renders normally (NOT greyed like `disabled`) but has no checkbox,
+     * is skipped by keyboard focus, and cannot be toggled or picked by Select-All.
+     * Options default to selectable. Tree mode only.
+     */
+    isSelectableMember?: string;
+    /**
+     * Callback deciding whether a tree node is selectable (takes precedence over
+     * `isSelectableMember`). Receives the built tree node, so `node.hasChildren` /
+     * `node.level` are available — e.g. `(node) => !node.hasChildren` for a
+     * leaves-only tree. Tree mode only.
+     */
+    getIsSelectableCallback?: (node: LTreeNode<T>) => boolean;
+    /**
+     * Tree checkbox interaction. `independent` (default) toggles only the clicked
+     * node. `cascade` checks a node's whole subtree and shows a tristate
+     * (checked / indeterminate / unchecked) box on branches. Tree + multiple only.
+     */
+    checkboxMode?: 'independent' | 'cascade';
+    /**
+     * In `cascade` mode, which values a selection emits (badges / form / change):
+     *   - `rolled-up` (default) — minimal cover: a fully-selected subtree collapses
+     *     to its root ("complete node"); partially-selected branches emit their
+     *     individually-checked descendants. Rolls to the nearest selectable
+     *     descendant when the complete node itself is non-selectable.
+     *   - `leaves` — only the checked leaf-level nodes.
+     *   - `all` — every fully-checked node (branches and leaves), like web-treeview.
+     */
+    cascadeSelectPolicy?: 'rolled-up' | 'leaves' | 'all';
     /** Member property name for group extraction */
     groupMember?: string;
     /** Callback to extract group from item */
@@ -186,6 +282,12 @@ declare interface MultiSelectConfig<T = any> {
     isAddNewAllowed?: boolean;
     /** Show count badge next to toggle icon (internal: isCounterShown) */
     isCounterShown?: boolean;
+    /**
+     * Make badges display each option's `fullTitleMember` / `getFullTitleCallback` value
+     * instead of its display value. Falls back to the display value for options without a
+     * full title. An explicit `getBadgeDisplayCallback` still takes precedence. Off by default.
+     */
+    isBadgeFullTitleShown?: boolean;
     /** Keep initial options visible when searchCallback is active and search term is empty/short (internal: isKeepOptionsOnSearch) */
     isKeepOptionsOnSearch?: boolean;
     /** Keep search text and filtered results when dropdown closes (default: true) */
@@ -232,6 +334,10 @@ 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') */
@@ -255,6 +361,23 @@ 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;
+    /**
+     * 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
@@ -264,12 +387,12 @@ declare interface MultiSelectConfig<T = any> {
     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) */
@@ -286,6 +409,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) */
@@ -313,13 +448,18 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     private _getIconCallback?;
     private _subtitleMember?;
     private _getSubtitleCallback?;
+    private _getFullTitleCallback?;
     private _groupMember?;
     private _getGroupCallback?;
     private _renderGroupLabelContentCallback?;
     private _disabledMember?;
     private _getDisabledCallback?;
+    private _getPathCallback?;
+    private _isTreeEnabled?;
+    private _getIsSelectableCallback?;
     private _getValueFormatCallback?;
     private _getBadgeTooltipCallback?;
+    private _getOptionTooltipCallback?;
     private _getRemoveButtonTooltipCallback?;
     private _renderOptionContentCallback?;
     private _renderBadgeContentCallback?;
@@ -332,11 +472,13 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     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();
     /**
@@ -398,10 +540,28 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     get iconMember(): string | null;
     set subtitleMember(value: string | null);
     get subtitleMember(): string | null;
+    set fullTitleMember(value: string | null);
+    get fullTitleMember(): string | null;
     set groupMember(value: string | null);
     get groupMember(): string | null;
     set disabledMember(value: string | null);
     get disabledMember(): string | null;
+    set pathMember(value: string | null);
+    get pathMember(): string | null;
+    set parentPathMember(value: string | null);
+    get parentPathMember(): string | null;
+    set levelMember(value: string | null);
+    get levelMember(): string | null;
+    set hasChildrenMember(value: string | null);
+    get hasChildrenMember(): string | null;
+    set isSelectableMember(value: string | null);
+    get isSelectableMember(): string | null;
+    set treePathSeparator(value: string | null);
+    get treePathSeparator(): string | null;
+    set checkboxMode(value: 'independent' | 'cascade' | null);
+    get checkboxMode(): 'independent' | 'cascade' | null;
+    set cascadeSelectPolicy(value: 'rolled-up' | 'leaves' | 'all' | null);
+    get cascadeSelectPolicy(): 'rolled-up' | 'leaves' | 'all' | null;
     set getValueCallback(callback: ((item: T) => string | number) | undefined);
     get getValueCallback(): ((item: T) => string | number) | undefined;
     set getDisplayValueCallback(callback: ((item: T) => string) | undefined);
@@ -418,8 +578,24 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     get getIconCallback(): ((item: T) => string) | undefined;
     set getSubtitleCallback(callback: ((item: T) => string) | undefined);
     get getSubtitleCallback(): ((item: T) => string) | undefined;
+    /** Callback returning an option's full title (used by badges when show-badge-full-title is on). */
+    set getFullTitleCallback(callback: ((item: T) => string) | undefined);
+    get getFullTitleCallback(): ((item: T) => string) | undefined;
     set getGroupCallback(callback: ((item: T) => string) | undefined);
     get getGroupCallback(): ((item: T) => string) | undefined;
+    /** Callback returning an option's materialized dot-path (enables tree mode). */
+    set getPathCallback(callback: ((item: T) => string) | undefined);
+    get getPathCallback(): ((item: T) => string) | undefined;
+    /** Force tree mode on/off. When unset, tree mode auto-enables if a path source is present. */
+    set isTreeEnabled(value: boolean | undefined);
+    get isTreeEnabled(): boolean | undefined;
+    /**
+     * Callback deciding whether a tree node is selectable (takes precedence over
+     * `is-selectable-member`). Receives the built node — e.g.
+     * `el.getIsSelectableCallback = (node) => !node.hasChildren` for leaves only.
+     */
+    set getIsSelectableCallback(callback: ((node: LTreeNode<T>) => boolean) | undefined);
+    get getIsSelectableCallback(): ((node: LTreeNode<T>) => boolean) | undefined;
     set renderGroupLabelContentCallback(callback: ((groupName: string) => string | HTMLElement) | undefined);
     get renderGroupLabelContentCallback(): ((groupName: string) => string | HTMLElement) | undefined;
     set getDisabledCallback(callback: ((item: T) => boolean) | undefined);
@@ -448,6 +624,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);
@@ -460,16 +648,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 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;
@@ -521,11 +713,22 @@ export declare interface MultiSelectOptions extends MultiSelectConfig<MultiSelec
     options?: MultiSelectOption[];
     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;
 }
 
+/**
+ * LTreeNode — a single node in the option tree.
+ *
+ * Trimmed lift of web-treeview's `ltree/ltree-node.ts`. The multiselect renders
+ * every node expanded (no collapse), so this keeps only the structural fields
+ * needed to order nodes and indent them: path/parent/level/children/hasChildren
+ * plus the original option `data`. Expand state, drag-drop, checkbox, selection
+ * and drop-position fields are all thrown out.
+ */
+declare type NodeId = string | number;
+
 /**
  * Context provided to renderOptionContentCallback
  */
@@ -584,6 +787,10 @@ export declare class WebMultiSelect<T = any> {
     private selectedOptions;
     private allOptions;
     private filteredOptions;
+    private tree;
+    private treeNodes;
+    private cascadeIndex;
+    private cascadeCheckedAtoms;
     private hiddenInputs;
     private focusedIndex;
     private matchingIndices;
@@ -637,14 +844,72 @@ export declare class WebMultiSelect<T = any> {
      * text independently. Doesn't fit the extractField shape (no tuple/member layer of its own).
      */
     private getItemBadgeDisplayValue;
+    /**
+     * Full title — a fully-qualified label supplied with the data (never computed here). Used by
+     * badges when `isBadgeFullTitleShown` is on. Returns undefined when the option has none.
+     */
+    private getItemFullTitle;
     private getItemSearchValue;
     private getItemIcon;
     private getItemSubtitle;
     private getItemGroup;
     private getItemDisabled;
+    /**
+     * Tree mode: whether the visible node at `index` may be selected. Non-selectable
+     * nodes (see `isSelectableMember`/`getIsSelectableCallback`) still render — just
+     * without a checkbox — but are skipped by focus and cannot be toggled. Always
+     * true outside tree mode. `treeNodes` is index-aligned with `filteredOptions`.
+     */
+    private isIndexSelectable;
+    /** Whether an option may be selected. Always true outside tree mode. */
+    private isOptionSelectable;
     constructor(element: HTMLElement, options?: Partial<MultiSelectConfig<T>>);
     private init;
     private parseOptions;
+    /** Whether options should be rendered as an (always-expanded) tree. */
+    private isTreeMode;
+    /** (Re)build the ltree from `allOptions` and derive the visible flat list. */
+    private buildTree;
+    /**
+     * Whether cascade checkbox mode is active: a multi-select tree with
+     * `checkbox-mode="cascade"`. Checking a node then toggles its whole subtree
+     * and branches show a tristate box.
+     */
+    private isCascadeMode;
+    private cascadePolicy;
+    /** Refresh the derived checked-atom set from the emitted `selectedValues`. */
+    private refreshCascadeAtoms;
+    /**
+     * Toggle a tree node in cascade mode: flip its whole subtree, re-project the
+     * checked atoms to emitted values under the active policy, and commit the diff
+     * so badges / form / change events reflect the policy (rolled-up branches, etc.).
+     */
+    private toggleTreeCascade;
+    /**
+     * Derive `treeNodes` + `filteredOptions` from the full tree, applying the
+     * current search term. Matching nodes keep all their ancestors visible so
+     * indentation stays coherent (the tree is always fully expanded).
+     */
+    private rebuildTreeVisible;
+    /**
+     * Reset the visible list to "everything". **Tree-aware**: in tree mode it
+     * rebuilds `treeNodes` (kept index-aligned with `filteredOptions`) from the
+     * full tree, so the two never drift. A raw `filteredOptions = [...allOptions]`
+     * would leave `treeNodes` stale after clearing a search — the virtual list
+     * then reserves height for every option but renders blank rows because
+     * `treeNodes[index]` is undefined. Always use this to clear the visible list.
+     */
+    private resetVisibleToAll;
+    /**
+     * Tree mode: derive the visible list from an **external** set of matched
+     * options — e.g. the results returned by `searchCallback` — keeping each
+     * match's ancestors so indentation stays coherent. This is the async-search
+     * analogue of `rebuildTreeVisible`: the matching is done by the caller (their
+     * own index/engine) instead of a local substring test, but ancestor
+     * preservation and `treeNodes`/`filteredOptions` index-alignment still happen
+     * here. Pass all options to show the whole tree.
+     */
+    private rebuildTreeVisibleFromMatches;
     private buildHTML;
     /**
      * Check if virtual scroll should be used
@@ -663,8 +928,24 @@ 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;
+    /**
+     * Render a single tree-mode row. Separate from `renderOption`: a tree row is
+     * indented by its depth (via the `--ms-tree-depth` custom property) and
+     * tagged branch/leaf, but otherwise carries the same selection/checkbox/
+     * icon/subtitle content. The tree is always fully expanded, so there is no
+     * chevron/toggle — every node is just a normal, selectable option.
+     */
+    private renderTreeNode;
     private highlightMatch;
     private groupOptions;
     /** Whether the input currently functions as a usable search field (drives placeholder wording). */
@@ -701,6 +982,13 @@ export declare class WebMultiSelect<T = any> {
      * Returning -1 from `compute` is a no-op (used for empty list / no match).
      */
     private focusBy;
+    /**
+     * Given a target index and a preferred direction, return the nearest index
+     * whose node is selectable (skipping non-selectable tree nodes). Falls back to
+     * the opposite direction, then to -1 if nothing is selectable. No-op outside
+     * tree mode.
+     */
+    private resolveSelectableIndex;
     private focusNext;
     private focusPrevious;
     private focusFirst;
@@ -711,6 +999,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;
@@ -719,7 +1024,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;
@@ -803,6 +1108,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`