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

package/README.md

@@ -21,6 +21,17 @@ 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-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.
+
 ## 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.
@@ -34,13 +45,6 @@ Reads `--base-*` variables from the page if [`@keenmate/theme-designer`](https:/
 - **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.
 
 ## Demos & docs

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);
@@ -591,6 +718,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 +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;
@@ -702,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
@@ -738,6 +938,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 +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;