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

package/README.md

@@ -21,11 +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
+## What's New in v1.12.0-rc04
 
-**v1.12.0-rc02** — Badge tooltips now theme correctly when portaled (real dark-mode contrast fix); FOUC-prevention rule renamed to match the actual tag; README split into slim landing page + `docs/` (usage, theming, examples, accessibility). See [CHANGELOG.md](./CHANGELOG.md) for details.
+- **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.
 
-**v1.12.0-rc01** — Dark mode responds to framework theme classes (`data-bs-theme`, `.dark`, `data-theme`) via Strategy B; CSS cascade layers; canonical Tier 1+2+3 file structure; BEM-aligned class names.
+## What's New in v1.12.0-rc03
+
+- **Declarative options — `<option>` children render without member attributes** — Declarative `<option>` / `<optgroup>` markup previously required `value-member` / `display-value-member` / `group-member` to be set, or every row rendered as `[N/A]`. The element now auto-wires those member properties (plus `icon`/`subtitle`/`disabled`) when declarative children are detected — only when the consumer hasn't already configured them — so markup-only usage works out of the box while every override path still wins.
+- **Framework events — bubbling + composed dispatch** — `select`, `deselect`, and `change` are now dispatched with `bubbles: true, composed: true`, so Svelte 5 `onchange={fn}`, React `onChange`, Vue `@change`, and any framework using delegated event routing work without the legacy `on:` directive. **Behavior change:** delegated form-level `change` listeners now also receive the component's event — filter by `e.target.tagName === 'WEB-MULTISELECT'` if your form library reacts to every `change`.
 
 > ⚠️ **Security notice:** This component intentionally allows raw HTML in rendering callbacks to give developers full control over content display. If you display user-generated content, you must sanitize it yourself. See [docs/examples.md → HTML Injection (XSS) notice](./docs/examples.md#html-injection-xss-notice) for the complete list of affected callbacks.
 
@@ -106,6 +112,11 @@ npm run build
 
 # Create package tarball
 npm run package
+
+# Run tests
+npm run test:unit   # Vitest (happy-dom) — fast logic checks
+npm run test:e2e    # Playwright (browser) — interaction/visual
+npm test            # both
 ```
 
 ## License

package/dist/index.d.ts

@@ -196,8 +196,20 @@ declare interface MultiSelectConfig<T = any> {
     checkboxAlign?: 'top' | 'center' | 'bottom';
     /** Hint text shown above the input while the dropdown is open. */
     searchHint?: string;
-    /** Placeholder text for the search input */
+    /** Placeholder text for the search input (shown while search is usable) */
     searchPlaceholder?: string;
+    /**
+     * Placeholder shown when search is disabled (input acts as a picker rather than a search box).
+     * Applies when `isSearchEnabled` is false or `searchInputMode` is 'readonly'/'hidden'.
+     * Default: "Pick an option..."
+     */
+    selectPlaceholder?: string;
+    /**
+     * Placeholder shown when there are no options to choose from (e.g. an unresolved cascade parent).
+     * Opt-in: when unset, the normal search/select placeholder is used even with an empty list.
+     * Lets users see there is no data without opening the dropdown.
+     */
+    noDataPlaceholder?: string;
     /** Minimum width for the dropdown (e.g., '20rem', '300px') */
     dropdownMinWidth?: string | null;
     /** Maximum width for the dropdown (e.g., '40rem', '500px') */
@@ -226,6 +238,13 @@ declare interface MultiSelectConfig<T = any> {
     badgesMaxVisible?: number | null;
     /** Minimum search length before loading data */
     minSearchLength?: number;
+    /**
+     * Debounce delay in milliseconds before the async `searchCallback` is invoked.
+     * Each keystroke resets the timer, so only the last input in a burst fires a request.
+     * Applies to the async `searchCallback` path only — local in-memory filtering stays instant.
+     * Default: 0 (no debounce — callback runs on every keystroke).
+     */
+    searchDebounce?: number;
     /** Minimum items before virtual scroll activates (default: 100) */
     virtualScrollThreshold?: number;
     /** Fixed height for each option in pixels (required for virtual scroll, default: 50) */
@@ -236,8 +255,13 @@ declare interface MultiSelectConfig<T = any> {
     virtualScrollBuffer?: number;
     /** Pre-process search term before calling searchCallback. Return null to prevent search. Use for accent removal, validation, etc. */
     beforeSearchCallback?: ((searchTerm: string) => string | null) | null;
-    /** Async function to load data: (searchTerm) => Promise<options[]> */
-    searchCallback?: ((searchTerm: string) => Promise<T[]>) | null;
+    /**
+     * Async function to load data: `(searchTerm, signal) => Promise<options[]>`.
+     * The optional second argument is an `AbortSignal` that fires when a newer search
+     * supersedes this one (or the component is destroyed). Wire it into your `fetch`
+     * to cancel the in-flight request; ignoring it is fine — stale results are discarded.
+     */
+    searchCallback?: ((searchTerm: string, signal?: AbortSignal) => Promise<T[]>) | null;
     /** Callback to add a new option when isAddNewAllowed is true */
     addNewCallback?: ((value: string) => T | Promise<T>) | null;
     /** Callback when an option is selected */
@@ -275,6 +299,7 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     private shadow;
     private internals?;
     private _options?;
+    private _hasDeclarativeOptions;
     private _valueMember?;
     private _getValueCallback?;
     private _displayValueMember?;
@@ -303,6 +328,9 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     private _renderSelectedContentCallback?;
     private _getCounterCallback?;
     private _actionButtons?;
+    private _batchDepth;
+    private _batchPartial;
+    private _batchNeedsReinit;
     private _beforeSearchCallback?;
     private _searchCallback?;
     private _addNewCallback?;
@@ -322,6 +350,20 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Set several attributes in one in-place update — a single re-render instead of one per
+     * attribute (and a single reinit at most if any change is structural). Keys are attribute
+     * names in kebab-case, exactly as `setAttribute`. A value of `null`/`undefined`/`false`
+     * removes the attribute; `true` sets it to an empty string; anything else is stringified.
+     *
+     * @example
+     *   el.setAttributes({
+     *     'search-placeholder': t('search'),
+     *     'select-placeholder': t('pick'),
+     *     'no-data-placeholder': t('noData'),
+     *   });
+     */
+    setAttributes(attrs: Record<string, string | number | boolean | null | undefined>): void;
     private render;
     private renderDebugInfo;
     private updateDebugInfo;
@@ -418,8 +460,8 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
     get getCounterCallback(): ((count: number, moreCount?: number) => string) | undefined;
     get beforeSearchCallback(): ((searchTerm: string) => string | null) | undefined;
     set beforeSearchCallback(callback: ((searchTerm: string) => string | null) | undefined);
-    get searchCallback(): ((searchTerm: string) => Promise<T[]>) | undefined;
-    set searchCallback(callback: ((searchTerm: string) => Promise<T[]>) | undefined);
+    get 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;
@@ -477,7 +519,7 @@ export declare interface MultiSelectOption {
  */
 export declare interface MultiSelectOptions extends MultiSelectConfig<MultiSelectOption> {
     options?: MultiSelectOption[];
-    searchCallback?: ((searchTerm: string) => Promise<MultiSelectOption[]>) | null;
+    searchCallback?: ((searchTerm: string, signal?: AbortSignal) => Promise<MultiSelectOption[]>) | null;
     addNewCallback?: ((value: string) => MultiSelectOption | Promise<MultiSelectOption>) | null;
     selectCallback?: ((option: MultiSelectOption) => void) | null;
     deselectCallback?: ((option: MultiSelectOption) => void) | null;
@@ -547,6 +589,8 @@ export declare class WebMultiSelect<T = any> {
     private matchingIndices;
     private searchTerm;
     private isLoading;
+    private searchDebounceTimer?;
+    private searchAbortController?;
     private showSelectedPopover;
     private selectedPopoverPlacement;
     private dropdownPlacement;
@@ -623,9 +667,31 @@ export declare class WebMultiSelect<T = any> {
     private renderOption;
     private highlightMatch;
     private groupOptions;
+    /** Whether the input currently functions as a usable search field (drives placeholder wording). */
+    private get isSearchUsable();
+    /**
+     * Resolve the closed-state input placeholder for the current data/search state.
+     * Priority: explicit no-data placeholder (when the list is empty) → "pick" prompt when
+     * search is unusable → the search placeholder.
+     */
+    private getPlaceholderText;
     private renderBadges;
     private attachEvents;
     private handleSearch;
+    /** Abort the search request currently in flight, if any. The aborted request's results
+     *  are then ignored (and the consumer's `searchCallback` can short-circuit its fetch via
+     *  the `AbortSignal` it was handed). */
+    private abortInFlightSearch;
+    /**
+     * Invoke the async `searchCallback` and apply its results. Split out of `handleSearch`
+     * so it can be called immediately or after the debounce timer.
+     *
+     * Any request still in flight is aborted before a new one starts, so a slow earlier
+     * request can't overwrite a newer one — and consumers that wire the passed `AbortSignal`
+     * into their fetch get the request actually cancelled, not just ignored. The
+     * `aborted` / `searchTerm === value` guards drop superseded or out-of-order responses.
+     */
+    private performAsyncSearch;
     private handleKeydown;
     private handleDropdownClick;
     private handleBadgeClick;