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

package/README.md

@@ -21,25 +21,22 @@ 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 in v1.12.0-rc05
-
-> ⚠️ **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.
-
-- **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.
+## What's New in v1.12.0-rc07
+
+- **Selection — `setSelected(values, { notify: true })` announces programmatic changes** — `setSelected()` stays silent by default (restoring saved state, cascade/dependent resets, and server-authoritative corrections must not re-fire `change`, or they trip "the user changed it" handlers and can bounce in a feedback loop), but the new `{ notify: true }` option fires a **single aggregate `change`** — no per-item `select`/`deselect` flood — for when a programmatic change is a deliberate user gesture, e.g. a custom action button that sets the selection and should reach the same listeners a manual pick does. Threaded through both the internal picker and the web component's `setSelected`.
+- **Cascade mode — Select All now honours the value policy** — the built-in `select-all` action added every selectable node's value directly, bypassing the cascade projection, so with `checkbox-mode="cascade"` + `cascade-select-policy="rolled-up"` it emitted every node instead of the rolled-up roots (unlike a click, which rolls up). `selectAll()` is now cascade-aware — it fills the checked-atom set from the visible nodes and projects through the active policy via a shared `commitCascadeAtoms` helper — so Select All emits the same shape a click does. Shown in the new "Action Buttons" section of `examples-tree.html`.
+- **Options no longer text-select on click-drag** — clicking a row, or dragging across the dropdown, used to highlight the labels like selectable text, which reads as broken for a pure selection gesture (most visible on the denser tree rows). Options now set `user-select: none` (with the `-webkit-` prefix) on `.ms__option`. Purely presentational — no API or behaviour change.
+
+## What's New in v1.12.0-rc06
+
+- **Tree of options — options can render as an always-expanded hierarchy** — give each option a materialized dot-path (`"1"`, `"1.1"`, `"1.1.1"`, …) and set `path-member` (or `el.getPathCallback`) and tree mode auto-enables, deriving parent/level from the path and rendering depth-first with indentation. The hierarchy model is a trimmed lift of `@keenmate/web-treeview`'s `ltree` (`src/tree/`) so ordering matches the treeview. There is no collapse/chevron — reach for `@keenmate/web-treeview` when you need expand/collapse. A separate `renderTreeNode` path carries the same selection/checkbox/icon/subtitle content plus depth indentation (via `--ms-tree-depth` → `src/css/tree.css`, tuned with `--ms-tree-indent`), and search filters the hierarchy to matches plus their ancestors so indentation stays coherent.
+- **Per-node selectability — mark tree nodes non-selectable without greying them out** — `is-selectable-member` (a data flag) or `el.getIsSelectableCallback` (a predicate over the built `LTreeNode`, so it can read the derived `node.hasChildren`) makes the common "leaves only" rule a one-liner. A non-selectable node is distinct from a disabled one: it renders *normally* but drops its checkbox, is skipped by keyboard focus, and can't be toggled by click/Enter or Select All. New `.ms__option--tree-unselectable` theming hook (plus `data-selectable="false"`) ships with only `cursor: default` and no hover highlight, so structural branch rows read as structure while staying visually normal.
+- **External search now composes with tree mode** — previously the async `searchCallback` path set the flat `filteredOptions` but not the parallel `treeNodes`, so an externalized search over a tree rendered blank or mis-indexed. It now rebuilds the hierarchy from the returned matches, keeping their ancestors (`rebuildTreeVisibleFromMatches`) — the async analogue of the built-in matches-plus-ancestors behaviour — and the below-min-length / error fallbacks are tree-aware too. A new `examples-search-index.html` demonstrates delegating the whole search to FlexSearch (fuzzy / accent-insensitive / ranked) over both a flat list and the full ISCO-08 tree, with an exact/prefix code lookup so `2211` resolves to its node and `72` to the whole subtree. FlexSearch stays a dev/consumer dependency — never in the shipped bundle.
+- **Badge full title — render a supplied breadcrumb on badges** — new `full-title-member` (or `el.getFullTitleCallback`) reads a fully-qualified label that ships with the data (e.g. `"Fruit / Pome fruit / Apple"`); it is never computed. Turn on `show-badge-full-title` and badges render that full title instead of the display value, falling back to the display value for options without one, while an explicit `getBadgeDisplayCallback` still wins. Pairs naturally with tree mode to show the full path in the badge.
+- **Adjustable row height and long-title handling** — new CSS variables (no new attributes) control every `.ms__option`, flat and tree: `--ms-option-min-height` sets a consistent minimum row height for non-virtual rows (they still grow if content is taller; virtual rows keep the fixed `--ms-option-height`), and `--ms-option-title-white-space` / `-overflow` / `-text-overflow` flip a title from the default wrap to a one-line ellipsis. `.ms__option-title` is the label hook (the analog of web-treeview's `.wtv__node-label`), and because its flex ancestors already set `min-width: 0`, ellipsis works with no extra CSS — pair it with `enable-option-tooltips` to reveal the full text on hover.
+- **Cascade checkboxes for tree mode, with a value policy** — set `checkbox-mode="cascade"` and checking a node toggles its whole subtree while a partially-selected branch shows a tristate (dash) box. Orthogonally, `cascade-select-policy` decides *which values* the selection emits: `rolled-up` (default) collapses a fully-selected subtree to one "complete node" value and surfaces individual descendants under partially-selected branches (the minimal cover — the bit svelte-treeview lacks); `leaves` emits only checked leaves; `all` emits every checked node like web-treeview. Canonical state is the set of checked leaf atoms and the emitted `selectedValues` is a pure projection, so badges/form/`change` are untouched and every policy round-trips. Non-breaking — `independent` (the previous behaviour) is the default. Logic is isolated in `src/tree/cascade.ts`; tristate renders from a CSS modifier class (virtual-scroll-safe). Demoed as §10 on `examples-tree.html`.
+- **More pronounced option checkboxes** — the unchecked box draws its border from a dedicated mid-grey token (`--ms-checkbox-border-color`, default `#8f8f8f`) instead of the faint generic `--ms-border`, so it reads as a real, clickable control, with a slightly bolder checkmark. New themeable tokens `--ms-checkbox-border-width` (1px), `--ms-checkbox-border-color`, and `--ms-checkbox-checkmark-thickness` drive it, and `--ms-checkbox-border` / `--ms-checkbox-checked-border` recompose from the width token — override any of them to restyle.
+- **Fixes — stable tree rows across search** — two virtual-scroll/tree regressions are fixed: row height no longer jumps as filtering crosses the virtual-scroll threshold (non-virtual rows now pin to `--ms-option-height` when virtual scroll is enabled), and clearing a search with Escape (or reopening after a search) no longer leaves the dropdown blank — both the Escape-clear and `close()` paths route through a tree-aware `resetVisibleToAll()` that rebuilds `treeNodes` from the full tree.
 
 > ⚠️ **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.
 

package/dist/index.d.ts

@@ -120,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
@@ -137,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 */
@@ -153,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 */
@@ -199,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) */
@@ -359,11 +448,15 @@ 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?;
@@ -447,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);
@@ -467,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);
@@ -540,7 +667,9 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     get selectedValue(): string | number | (string | number)[] | null;
     get selectedItem(): T | null;
     getSelected(): T[];
-    setSelected(values: (string | number)[]): void;
+    setSelected(values: (string | number)[], opts?: {
+        notify?: boolean;
+    }): void;
     getValue(): string | number | (string | number)[] | null;
     destroy(): void;
 }
@@ -591,6 +720,17 @@ export declare interface MultiSelectOptions extends MultiSelectConfig<MultiSelec
     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
  */
@@ -649,6 +789,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;
@@ -702,14 +846,79 @@ 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;
+    /**
+     * Given a checked-atom set, project it to emitted values under the active
+     * policy, diff it against the current selection, and commit. Shared by every
+     * cascade entry point (node toggle, Select All) so they all emit the same
+     * policy-projected shape (e.g. a full subtree rolls up to one value).
+     */
+    private commitCascadeAtoms;
+    /**
+     * 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
@@ -738,6 +947,14 @@ export declare class WebMultiSelect<T = any> {
     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). */
@@ -774,6 +991,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;
@@ -866,7 +1090,18 @@ export declare class WebMultiSelect<T = any> {
     private updateHiddenInput;
     private getFormValue;
     getSelected(): T[];
-    setSelected(values: (string | number)[]): void;
+    /**
+     * Set the selection programmatically. **Silent by default** — it does not fire
+     * `select`/`deselect`/`change` (so restoring saved state, cascade resets, or a
+     * server-authoritative correction can't loop back or trip "user changed it"
+     * handlers). Pass `{ notify: true }` to announce the result as a **single
+     * aggregate `change`** — for a deliberate user gesture (e.g. an action button)
+     * that should reach the same listeners a manual pick does, without the per-item
+     * `select`/`deselect` flood a bulk change would otherwise cause.
+     */
+    setSelected(values: (string | number)[], opts?: {
+        notify?: boolean;
+    }): void;
     /**
      * Merge a partial config update into the live picker without tearing down the DOM.
      *