@keenmate/web-multiselect 2.0.0-rc11 → 2.0.0

package/dist/index.d.ts

@@ -332,8 +332,32 @@ declare interface MultiSelectConfig<T = any> {
     fullscreenAutofocus?: boolean;
     /** Lock dropdown placement after first open (internal: isPlacementLocked) */
     isPlacementLocked?: boolean;
-    /** Allow adding new options not in the list (internal: isAddNewAllowed) */
+    /**
+     * Allow adding new options not in the list (internal: isAddNewAllowed).
+     * When on and a search yields no matches, the empty dropdown shows a clickable
+     * "add new" prompt (text from `addNewText` / `getAddNewTextCallback`) instead of
+     * the `emptyMessage`; choosing it (click or Enter) fires the `add` event and, if
+     * `addNewCallback` is set, materializes + selects the created option.
+     */
     isAddNewAllowed?: boolean;
+    /**
+     * Template for the clickable "add new" prompt (see `isAddNewAllowed`). The substring
+     * `{value}` is replaced with the (HTML-escaped) typed text. Default: `Add "{value}"`.
+     * `getAddNewTextCallback` takes precedence. (internal: addNewText)
+     */
+    addNewText?: string;
+    /**
+     * Dynamically compute the "add new" prompt label from the typed text. Takes precedence
+     * over `addNewText`. Returns plain text (inserted as text, not HTML). Use it for i18n or
+     * context-aware wording, e.g. `(v) => \`Add new member: ${v}\``.
+     */
+    getAddNewTextCallback?: ((value: string) => string) | null;
+    /**
+     * Template for the pending prompt shown (spinner + this text) while an async `addNewCallback`
+     * is in flight. `{value}` is replaced with the (HTML-escaped) typed text. Default:
+     * `Adding "{value}"…`. (internal: addNewPendingText)
+     */
+    addNewPendingText?: string;
     /** Show count badge next to toggle icon (internal: isCounterShown) */
     isCounterShown?: boolean;
     /**
@@ -343,6 +367,13 @@ declare interface MultiSelectConfig<T = any> {
      * Default `false`. (internal: isClearShown)
      */
     isClearShown?: boolean;
+    /**
+     * Scope the "one overlay open at a time" coordination to a named group. Overlays
+     * (multiselects, datepickers, external popovers) sharing a group dismiss each other
+     * when one opens; different groups are independent. Unset = the default (ungrouped)
+     * group, in which every ungrouped overlay coordinates. (internal: overlayGroup)
+     */
+    overlayGroup?: string;
     /**
      * Allow the selected-items popover to open. Defaults to `true`. The popover is triggered by
      * the count / compact / "+X more" badge and by the in-input counter (`isCounterShown`). Set
@@ -523,8 +554,32 @@ declare interface MultiSelectConfig<T = any> {
      * 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 to create the new option object from the typed text when `isAddNewAllowed` is on.
+     * Return (or resolve to) the new option — it is appended to the list and auto-selected. The
+     * returned `T` can be a rich option object (icon/subtitle/custom-render fields and all): it flows
+     * through the same `get*` / `render*` callbacks as any other option, so the created row and its
+     * badge render exactly like the rest.
+     *
+     * **Cancelable (async):** return `null` or `undefined` (or a Promise of either) to abort — nothing
+     * is added or selected, the search is left intact, and the `add` event does NOT fire. Use it for
+     * async validation, a confirm dialog, or a server round-trip that may say no. The cancel sentinel
+     * is strictly `null`/`undefined` (checked with `== null`), so a falsy-but-valid option in
+     * primitive mode (`0`, `false`, `""`) still creates normally.
+     *
+     * Omit the callback entirely to handle creation yourself via the `add` event / `onAddNew` (e.g.
+     * open a modal, POST to a server, then add the option imperatively).
+     */
+    addNewCallback?: ((value: string) => T | null | undefined | Promise<T | null | undefined>) | null;
+    /**
+     * Event handler: the user chose to create a new option from the typed text (via the "add new"
+     * row or Enter). `value` is the typed text; `option` is the created item when `addNewCallback`
+     * produced one (absent otherwise). Mirrors the bubbling `add` CustomEvent on the element.
+     */
+    onAddNew?: ((detail: {
+        value: string;
+        option?: T;
+    }) => void) | null;
     /**
      * Intercept keyboard input before the built-in handling. Runs on every keydown (open or
      * closed) with a {@link MultiSelectKeydownContext} carrying the event, current state, and a
@@ -599,10 +654,14 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
     }, {
         readonly name: "change";
         readonly description: "The selection changed. `detail.selectedOptions`/`detail.selectedValues` are the full selection.";
+    }, {
+        readonly name: "add";
+        readonly description: "The user chose to create a new option from the typed text (via the \"add new\" prompt or Enter) — requires `allow-add-new`. `detail.value` is the typed text; `detail.option` is the created item when `addNewCallback` produced one.";
     }];
     onSelect: ((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null;
     onDeselect: ((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null;
     onChange: ((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null;
+    onAdd: ((e: CustomEvent<MultiSelectEventDetail<T>>) => void) | null;
     constructor();
     /**
      * Called by the browser when the surrounding <form> is reset. Clears the
@@ -660,6 +719,43 @@ export declare class MultiSelectElement<T = any> extends BlissElement<MultiSelec
     showMessage(content: string | HTMLElement, opts?: MessageOptions): void;
     /** Dismiss the transient message shown by {@link showMessage}, if any. */
     hideMessage(): void;
+    /**
+     * Clear the search box and restore the full option list (does not touch the selection — use
+     * {@link clearAll} for that). Pair with {@link scrollToValue} to reveal then scroll to an option
+     * a search had filtered out: `el.clearSearch(); el.scrollToValue(v)`.
+     */
+    clearSearch(): void;
+    /** The current search box text (empty string when nothing is typed). Read via this getter, write with {@link search}. */
+    get searchText(): string;
+    /**
+     * Programmatically set the search text and filter, as if the user typed it (runs
+     * `beforeSearchCallback` / `minSearchLength` / async `searchCallback`). Does not open the dropdown
+     * — call {@link open} if you want it visible. Pass `''` to clear (same as {@link clearSearch}).
+     */
+    search(term: string): void;
+    /**
+     * Scroll the open dropdown to the option at `index` (into the current filtered list). Returns
+     * false if closed or out of range. Deferred internally so `el.open(); el.scrollToIndex(i)` works.
+     */
+    scrollToIndex(index: number, opts?: {
+        block?: ScrollLogicalPosition;
+    }): boolean;
+    /**
+     * Scroll the open dropdown to the option with this `value`. Returns false if it isn't in the
+     * currently visible list (filtered out by search, or under a collapsed tree branch) — call
+     * {@link clearSearch} / expand first.
+     */
+    scrollToValue(value: string | number, opts?: {
+        block?: ScrollLogicalPosition;
+    }): boolean;
+    /**
+     * Scroll to a group: its header in standard rendering, or the group's first option in
+     * virtual-scroll mode (no headers there). Returns false in tree mode or if the group is empty
+     * in the current filtered list.
+     */
+    scrollToGroup(name: string, opts?: {
+        block?: ScrollLogicalPosition;
+    }): boolean;
     /** Open the dropdown. */
     open(): void;
     /** Close the dropdown. */
@@ -681,14 +777,17 @@ export declare interface MultiSelectEventDetail<T = any> {
     selectedOptions: T[];
     /** Selected values array */
     selectedValues: (string | number)[];
-    /** The option that triggered the event (for select/deselect) */
+    /** The option that triggered the event (for select/deselect/add) */
     option?: T;
+    /** The typed text that triggered the `add` event (add only) */
+    value?: string;
 }
 
 declare type MultiSelectEvents = {
     select: MultiSelectEventDetail;
     deselect: MultiSelectEventDetail;
     change: MultiSelectEventDetail;
+    add: MultiSelectEventDetail;
 };
 
 /**
@@ -936,6 +1035,10 @@ export declare class WebMultiSelect<T = any> {
     private keyboardController;
     private matchingIndices;
     private searchTerm;
+    /** Keyboard focus sits on the empty-state "add new" prompt (arrow-navigated). */
+    private addNewFocused;
+    /** An async addNewCallback is in flight — the prompt shows a spinner + pending text. */
+    private addNewPending;
     private isLoading;
     private searchDebounceTimer?;
     private searchAbortController?;
@@ -988,6 +1091,7 @@ export declare class WebMultiSelect<T = any> {
     private selectedPopover;
     private documentKeydownHandler;
     private documentClickHandler;
+    private overlayCoord;
     /**
      * Generic field extractor with the precedence:
      *   tuple short-circuit -> member property -> callback -> fallback
@@ -1184,6 +1288,25 @@ export declare class WebMultiSelect<T = any> {
      * chevron/toggle — every node is just a normal, selectable option.
      */
     private renderTreeNode;
+    /**
+     * Empty-dropdown content. When "add new" is enabled (isAddNewAllowed) AND the user has typed
+     * a non-empty search term, show a clickable "add new" prompt instead of the plain emptyMessage —
+     * choosing it (click via handleDropdownClick, or Enter via the keydown handler) runs handleAddNew.
+     * Otherwise fall back to the emptyMessage.
+     */
+    private renderEmptyStateHTML;
+    /** True when the empty dropdown is currently showing the clickable "add new" prompt. */
+    private isAddNewPromptShown;
+    /**
+     * Resolve the "add new" prompt label for the typed text. Priority: getAddNewTextCallback
+     * (returns plain text — fully escaped here) → addNewText template (trusted config string;
+     * only the `{value}` substitution is escaped) → the default `Add "{value}"`.
+     */
+    private getAddNewText;
+    /** Pending-prompt label shown (with a spinner) while an async addNewCallback runs. */
+    private getAddNewPendingText;
+    /** Minimal HTML entity escape for untrusted text spliced into an innerHTML string. */
+    private escapeHtml;
     private highlightMatch;
     private groupOptions;
     /** Whether the input currently functions as a usable search field (drives placeholder wording). */
@@ -1243,6 +1366,8 @@ export declare class WebMultiSelect<T = any> {
     private focusLast;
     private focusPageUp;
     private focusPageDown;
+    /** Move keyboard focus onto the empty-state "add new" prompt (the only actionable row). */
+    private focusAddNewPrompt;
     private focusNextMatch;
     private focusPreviousMatch;
     /** Lazily build (and cache) the imperative facade passed to `keydownCallback`. Bound to the
@@ -1250,8 +1375,64 @@ export declare class WebMultiSelect<T = any> {
     private getKeyboardController;
     /** Clear the search box (both the main input and the fullscreen search) and reset the visible
      *  list. Shared by Escape and the keyboard controller. */
-    private clearSearch;
+    /**
+     * Clear the search box and restore the full option list (resets the visible/matched sets and
+     * drops keyboard focus). Public building block: pair it with `scrollToValue()` to reveal then
+     * scroll to an option the current search had filtered out — `el.clearSearch(); el.scrollToValue(v)`.
+     * Does not touch the selection (use `clearAll()` for that).
+     */
+    clearSearch(): void;
+    /**
+     * Programmatically set the search text and filter — exactly as if the user typed it, so
+     * `beforeSearchCallback`, `minSearchLength` and async `searchCallback` all apply the same way.
+     * Reflects into the search box (and the fullscreen sheet's field). Does NOT open the dropdown —
+     * call `open()` if you want it visible. Passing `''` clears (equivalent to `clearSearch()`).
+     */
+    search(term: string): void;
     private scrollToFocused;
+    /**
+     * scrollIntoView with the fullscreen-safe default. In the fullscreen sheet the soft keyboard
+     * covers the lower viewport, so `block:'nearest'` can bottom-align a match BEHIND the keyboard;
+     * centre it instead and scroll INSTANTLY (a smooth animation kicked off per-keystroke is torn
+     * down by the next re-render and never settles — the "list jumps every letter" bug). Floating
+     * scrolls the nearest edge smoothly. The caller may override `block`.
+     */
+    private applyScrollIntoView;
+    /**
+     * Scroll the open dropdown so the option at `index` (into the current `filteredOptions`) is
+     * visible. Works in floating, fullscreen (mobile), virtual-scroll and tree modes. Returns
+     * false if the dropdown is closed or the index is out of range. The scroll is deferred a frame
+     * when the list isn't rendered yet (e.g. right after `open()` in virtual mode / the fullscreen
+     * sheet build), so `el.open(); el.scrollToIndex(i)` works.
+     */
+    scrollToIndex(index: number, opts?: {
+        block?: ScrollLogicalPosition;
+    }): boolean;
+    /**
+     * Scroll to the option whose value matches `value` (resolved within the current
+     * `filteredOptions`). Returns false if it isn't in the currently visible list — e.g. filtered
+     * out by a search, or (tree) under a collapsed ancestor. Call `clearSearch()` (or expand the
+     * branch) first to reveal it, then scroll.
+     */
+    scrollToValue(value: string | number, opts?: {
+        block?: ScrollLogicalPosition;
+    }): boolean;
+    /**
+     * Scroll to a group. In standard rendering the group's header (`.ms__group-label`) is brought
+     * into view; in virtual-scroll mode (which renders no headers) it scrolls to the group's FIRST
+     * option instead. Returns false in tree mode (groups don't apply) or if the group has no
+     * options in the current filtered list.
+     */
+    scrollToGroup(name: string, opts?: {
+        block?: ScrollLogicalPosition;
+    }): boolean;
+    /**
+     * Shared scroll worker for the public scrollTo* methods. Virtual mode uses the fixed-height
+     * math (works even if the row isn't currently rendered); otherwise scrolls the
+     * `.ms__option[data-index]` element into view. Defers one frame if the list isn't ready yet
+     * (post-open virtual init / fullscreen sheet build), then retries once.
+     */
+    private scrollToRenderedIndex;
     private toggleOption;
     /**
      * The single funnel for an interactive (user-initiated) selection. Consults
@@ -1270,6 +1451,13 @@ export declare class WebMultiSelect<T = any> {
      * Returns true if the option was deselected, false if the veto blocked it.
      */
     private interactiveDeselect;
+    /**
+     * Commit the "add new" affordance for the typed text. Two modes:
+     *  - `addNewCallback` set → create the option, append it, select it, clear the search.
+     *  - no callback → the consumer owns creation; we only notify (via the `add` event) so they
+     *    can open a modal / POST / add the option imperatively.
+     * The `add` event fires in BOTH modes (with `option` present only when one was created).
+     */
     private handleAddNew;
     private selectOption;
     private deselectOption;
@@ -1555,6 +1743,8 @@ export declare class WebMultiSelect<T = any> {
      */
     updateOptions(partial: Partial<MultiSelectConfig<T>>): boolean;
     get selectedItem(): T | null;
+    /** The current search box text (empty string when nothing is typed). Read-only; clear it with `clearSearch()`. */
+    get searchText(): string;
     get selectedValue(): string | number | (string | number)[] | null;
     getValue(): string | number | (string | number)[] | null;
     /**