@keenmate/web-multiselect 1.8.6 → 1.9.0

package/README.md

@@ -327,11 +327,15 @@ multiselect.addNewCallback = async (value) => {
 
 - **↑ ↓** - Navigate up/down through options
 - **Ctrl+↑ Ctrl+↓** - Jump between matched items (navigate mode only)
-- **Enter** - Select focused option
+- **Page Up / Page Down** - Move focus by 10 options at a time
+- **Home / End** - Jump to first / last option
+- **Enter** - Select focused option (or add new entry when `allow-add-new="true"` and the search has text)
 - **Escape** - Close popover → Clear search → Close dropdown (priority order)
 - **Tab** - Close dropdown and move to next field
 - **Type** - Filter options by search term
 
+> 💡 To surface these shortcuts to your users, set the `search-hint` attribute — the hint floats above the input when focused. Example: `<web-multiselect search-mode="navigate" search-hint="Ctrl/Cmd + ↓ / ↑ to jump between matches">`.
+
 ## Advanced Features
 
 ### Rich Content with Icons

package/dist/index.d.ts

@@ -321,8 +321,19 @@ export declare class MultiSelectElement<T = any> extends BaseElement {
      */
     private parseDeclarativeOptions;
     private _declarativeSelectedValues?;
+    /** Parse all observed attributes via ATTRIBUTE_TABLE into a partial config object. */
+    private parseAttributesFromTable;
     private initializePicker;
     private reinitialize;
+    /**
+     * Apply a partial config update to the live picker. Falls back to a full reinit if the
+     * picker can't apply the change in place (e.g. adding/removing the `searchHint` element).
+     * No-op if the picker hasn't been initialized yet — the next `initializePicker` will pick
+     * up the new programmatic state.
+     */
+    private updatePicker;
+    /** Normalize the picker's getValue() return into the array form expected by event detail. */
+    private collectSelectedValues;
     get options(): T[] | undefined;
     set options(value: T[] | undefined);
     set valueMember(value: string | null);
@@ -492,9 +503,10 @@ export declare type SearchInputMode = 'normal' | 'readonly' | 'hidden';
 export declare type SearchMode = 'filter' | 'navigate';
 
 /**
- * Set log level for a specific category
- * @param category Category logger to configure (e.g., 'MULTISELECT:UI')
- * @param level Log level to set ('trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent')
+ * Set log level for a specific category. Accepts either the full prefixed name
+ * (e.g. `MULTISELECT:UI`) or the bare suffix (`UI`) for convenience.
+ * @param category Category logger name; bare names (UI/DATA/INIT/INTERACTION) are normalized to the prefixed form.
+ * @param level Log level ('trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent')
  */
 export declare function setCategoryLevel(category: string, level: string): void;
 
@@ -534,12 +546,7 @@ export declare class WebMultiSelect<T = any> {
     private dropdownCleanup;
     private hintCleanup;
     private selectedPopoverCleanup;
-    private badgeTooltips;
-    private badgeTooltipCleanups;
-    private badgeTooltipShowTimeouts;
-    private badgeTooltipHideTimeouts;
-    private actionButtonTooltips;
-    private actionButtonTooltipCleanups;
+    private tooltips;
     private virtualScroll;
     private optionsContainer;
     private selectedPopoverVirtualScroll;
@@ -554,41 +561,31 @@ export declare class WebMultiSelect<T = any> {
     private documentKeydownHandler;
     private documentClickHandler;
     /**
-     * Extract value/ID from item
-     * Precedence: tuple[0] -> valueMember -> getValueCallback -> '[N/A]'
+     * Generic field extractor with the precedence:
+     *   tuple short-circuit -> member property -> callback -> fallback
+     *
+     * Tuple handling:
+     *   - `tupleIndex` (0 | 1): for `[key, value]` items, return that slot.
+     *   - `tupleSkip: true`: for any tuple, skip directly to fallback (used for icon/subtitle/group/disabled —
+     *     fields that don't make sense on a 2-element array).
+     *   - neither: tuples flow through the member/callback/fallback chain as if they were objects.
+     *
+     * `transform` is applied to tuple-slot and member-property reads (not to callback returns or the fallback),
+     * so e.g. you can pass `String` to coerce numeric members to strings while letting a typed callback return its
+     * own type unchanged.
      */
+    private extractField;
     private getItemValue;
-    /**
-     * Extract display value from item
-     * Precedence: tuple[1] -> displayValueMember -> getDisplayValueCallback -> '[N/A]'
-     */
     private getItemDisplayValue;
     /**
-     * Extract badge display value from item
-     * Precedence: getBadgeDisplayCallback -> getItemDisplayValue()
-     * This allows customizing badge text separately from dropdown display text
+     * Badge display falls back to the regular display value rather than '[N/A]', so consumers can override badge
+     * text independently. Doesn't fit the extractField shape (no tuple/member layer of its own).
      */
     private getItemBadgeDisplayValue;
-    /**
-     * Extract search value from item
-     * Precedence: searchValueMember -> getSearchValueCallback -> displayValue
-     */
     private getItemSearchValue;
-    /**
-     * Extract icon from item
-     */
     private getItemIcon;
-    /**
-     * Extract subtitle from item
-     */
     private getItemSubtitle;
-    /**
-     * Extract group from item
-     */
     private getItemGroup;
-    /**
-     * Extract disabled state from item
-     */
     private getItemDisabled;
     constructor(element: HTMLElement, options?: Partial<MultiSelectConfig<T>>);
     private init;
@@ -607,6 +604,11 @@ export declare class WebMultiSelect<T = any> {
      * Render dropdown with virtual scrolling
      */
     private renderDropdownVirtual;
+    /**
+     * Render the Select All / Clear All / custom action buttons row.
+     * Returns the empty string if multiple-select is off or no buttons are configured.
+     */
+    private renderActionsHTML;
     private renderOption;
     private highlightMatch;
     private groupOptions;
@@ -617,14 +619,19 @@ export declare class WebMultiSelect<T = any> {
     private handleDropdownClick;
     private handleBadgeClick;
     private handleClickOutside;
+    /**
+     * Move focus by computing a new index from (current, total).
+     * Returning -1 from `compute` is a no-op (used for empty list / no match).
+     */
+    private focusBy;
     private focusNext;
     private focusPrevious;
     private focusFirst;
     private focusLast;
-    private focusNextMatch;
-    private focusPreviousMatch;
     private focusPageUp;
     private focusPageDown;
+    private focusNextMatch;
+    private focusPreviousMatch;
     private scrollToFocused;
     private toggleOption;
     private handleAddNew;
@@ -632,8 +639,22 @@ export declare class WebMultiSelect<T = any> {
     private deselectOption;
     private selectAll;
     private clearAll;
+    /**
+     * 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.
+     */
+    private commit;
     private open;
     private close;
+    /**
+     * Anchor a floating panel (dropdown or selected-items popover) below/above the input with
+     * placement-locking and width-syncing. Returns the `autoUpdate` cleanup.
+     *
+     * Both panels share: anchor on input, sync width, default to 'bottom-start', flip on first
+     * compute then lock the resulting placement, optionally clamp by dropdownMin/MaxWidth.
+     */
+    private anchorFloatingPanel;
     private positionDropdown;
     private positionHint;
     private parseInitialSelection;
@@ -642,27 +663,60 @@ export declare class WebMultiSelect<T = any> {
     private hideSelectedPopover;
     private renderSelectedPopover;
     private renderSelectedPopoverVirtual;
-    private renderBadgeForPopover;
+    /**
+     * Render a removable badge for a selected option (used by the badges/partial display modes
+     * and by the selected-items popover).
+     *
+     * - In the popover, `renderSelectedItemContentCallback` and `getSelectedItemClassCallback` win
+     *   over the regular badge callbacks; that's how consumers customize popover items independently.
+     * - The `data-value` and aria-label both go through `getItemBadgeDisplayValue` so badge text and
+     *   accessible name stay in sync.
+     */
+    private renderBadgeHTML;
     private handleSelectedPopoverClick;
     private positionSelectedPopover;
     private updateHiddenInput;
     private getFormValue;
     getSelected(): T[];
     setSelected(values: (string | number)[]): void;
+    /**
+     * Merge a partial config update into the live picker without tearing down the DOM.
+     *
+     * Handles the cheap structural toggles inline (no-checkboxes class, badges-position class,
+     * input placeholder, search-input mode) and re-renders dropdown + badges + hidden inputs.
+     *
+     * Returns `true` if the change could be applied in place. Returns `false` for changes that
+     * truly require rebuilding the DOM scaffolding (currently: adding/removing the `searchHint`
+     * element, since it's only created in `buildHTML` if a hint string was provided). The caller
+     * should fall back to destroy + re-init in that case.
+     */
+    updateOptions(partial: Partial<MultiSelectConfig<T>>): boolean;
     get selectedItem(): T | null;
     get selectedValue(): string | number | (string | number)[] | null;
     getValue(): string | number | (string | number)[] | null;
+    /**
+     * Create or replace a tracked tooltip with the given id. Replacing destroys the old one,
+     * which is the normal flow when re-rendering badges/actions.
+     */
+    private spawnTooltip;
+    private destroyAllTooltips;
+    /** Build the badge-text tooltip content (callback overrides; default = displayValue + optional subtitle on next line). */
+    private buildBadgeTooltipContent;
+    /** Build the remove-button tooltip text (callback > format string with {0} > "Remove {name}"). */
+    private buildRemoveButtonTooltipText;
     private attachBadgeTooltips;
-    private createTooltipForElement;
-    private createRemoveButtonTooltip;
-    private positionBadgeTooltip;
-    private cleanupBadgeTooltip;
-    private destroyAllBadgeTooltips;
     private attachActionButtonTooltips;
-    private createActionButtonTooltip;
-    private positionActionButtonTooltip;
-    private cleanupActionButtonTooltip;
+    /**
+     * Destroy only the action-button tooltips. Called from `renderDropdown`/`renderDropdownVirtual`
+     * before rebuilding the actions row, so per-button tooltip state doesn't leak.
+     */
     private destroyAllActionButtonTooltips;
+    /**
+     * Destroy main-badges-container tooltips. Called before re-rendering the badges container.
+     * Popover tooltips (prefixed `popover-`) survive — they're owned by the popover lifecycle and
+     * cleaned up in `hideSelectedPopover`. Action-button tooltips (prefixed `action-`) survive too.
+     */
+    private destroyAllBadgeTooltips;
     destroy(): void;
 }