svelte-multiselect 11.5.1 → 11.6.0

package/dist/MultiSelect.svelte

@@ -5,17 +5,17 @@ import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import { highlight_matches } from './attachments';
 import CircleSpinner from './CircleSpinner.svelte';
 import Icon from './Icon.svelte';
-import { fuzzy_match, get_label, get_style, has_group, is_object } from './utils';
+import * as utils from './utils';
 import Wiggle from './Wiggle.svelte';
-let { activeIndex = $bindable(null), activeOption = $bindable(null), createOptionMsg = `Create this option...`, allowUserOptions = false, allowEmpty = false, autocomplete = `off`, autoScroll = true, breakpoint = 800, defaultDisabledTitle = `This option is disabled`, disabled = false, disabledInputTitle = `This input is disabled`, duplicateOptionMsg = `This option is already selected`, duplicates = false, keepSelectedInDropdown = false, key = (opt) => `${get_label(opt)}`.toLowerCase(), filterFunc = (opt, searchText) => {
+let { activeIndex = $bindable(null), activeOption = $bindable(null), createOptionMsg = `Create this option...`, allowUserOptions = false, allowEmpty = false, autocomplete = `off`, autoScroll = true, breakpoint = 800, defaultDisabledTitle = `This option is disabled`, disabled = false, disabledInputTitle = `This input is disabled`, duplicateOptionMsg = `This option is already selected`, duplicates = false, keepSelectedInDropdown = false, key = (opt) => `${utils.get_label(opt)}`.toLowerCase(), filterFunc = (opt, searchText) => {
     if (!searchText)
         return true;
-    const label = `${get_label(opt)}`;
+    const label = `${utils.get_label(opt)}`;
     return fuzzy
-        ? fuzzy_match(searchText, label)
+        ? utils.fuzzy_match(searchText, label)
         : label.toLowerCase().includes(searchText.toLowerCase());
 }, fuzzy = true, closeDropdownOnSelect = false, form_input = $bindable(null), highlightMatches = true, id = null, input = $bindable(null), inputClass = ``, inputStyle = null, inputmode = null, invalid = $bindable(false), liActiveOptionClass = ``, liActiveUserMsgClass = ``, liOptionClass = ``, liOptionStyle = null, liSelectedClass = ``, liSelectedStyle = null, liUserMsgClass = ``, loading = false, matchingOptions = $bindable([]), maxOptions = undefined, maxSelect = $bindable(null), maxSelectMsg = (current, max) => (max > 1 ? `${current}/${max}` : ``), maxSelectMsgClass = ``, name = null, noMatchingOptionsMsg = `No matching options`, open = $bindable(false), options = $bindable(), outerDiv = $bindable(null), outerDivClass = ``, parseLabelsAsHtml = false, pattern = null, placeholder = null, removeAllTitle = `Remove all`, removeBtnTitle = `Remove`, minSelect = null, required = false, resetFilterOnAdd = true, searchText = $bindable(``), value = $bindable(null), selected = $bindable(value !== null && value !== undefined
-    ? (Array.isArray(value) ? value : [value])
+    ? Array.isArray(value) ? value : [value]
     : (options
         ?.filter((opt) => typeof opt === `object` && opt !== null && opt?.preselected)
         .slice(0, maxSelect ?? undefined) ?? [])), sortSelected = false, selectedOptionsDraggable = !sortSelected, style = null, ulOptionsClass = ``, ulSelectedClass = ``, ulSelectedStyle = null, ulOptionsStyle = null, expandIcon, selectedItem, children, removeIcon, afterInput, spinner, disabledIcon, option, userMsg, onblur, onclick, onfocus, onkeydown, onkeyup, onmousedown, onmouseenter, onmouseleave, ontouchcancel, ontouchend, ontouchmove, ontouchstart, onadd, oncreate, onremove, onremoveAll, onchange, onopen, onclose, onselectAll, onreorder, portal: portal_params = {}, 
@@ -26,24 +26,24 @@ loadOptions,
 // Animation parameters for selected options flip animation
 selectedFlipParams = { duration: 100 }, 
 // Option grouping feature
-collapsibleGroups = false, collapsedGroups = $bindable(new Set()), groupSelectAll = false, ungroupedPosition = `first`, groupSortOrder = `none`, searchExpandsCollapsedGroups = false, searchMatchesGroups = false, keyboardExpandsCollapsedGroups = false, stickyGroupHeaders = false, liGroupHeaderClass = ``, liGroupHeaderStyle = null, groupHeader, ongroupToggle, oncollapseAll, onexpandAll, collapseAllGroups = $bindable(), expandAllGroups = $bindable(), 
+collapsibleGroups = false, collapsedGroups = $bindable(new Set()), groupSelectAll = false, ungroupedPosition = `first`, groupSortOrder = `none`, searchExpandsCollapsedGroups = false, searchMatchesGroups = false, keyboardExpandsCollapsedGroups = false, stickyGroupHeaders = false, liGroupHeaderClass = ``, liGroupHeaderStyle = null, groupHeader, ongroupToggle, oncollapseAll, onexpandAll, onsearch, onmaxreached, onduplicate, onactivate, collapseAllGroups = $bindable(), expandAllGroups = $bindable(), 
 // Keyboard shortcuts for common actions
-shortcuts = {}, ...rest } = $props();
+shortcuts = {}, 
+// Selection history for undo/redo (enabled by default, set to false or 0 to disable)
+history = true, undo = $bindable(), redo = $bindable(), canUndo = $bindable(false), canRedo = $bindable(false), onundo, onredo, ...rest } = $props();
 // Generate unique IDs for ARIA associations (combobox pattern)
 // Uses provided id prop or generates a random one using crypto API
-const internal_id = $derived(id ?? `sms-${crypto.randomUUID().slice(0, 8)}`);
+const internal_id = $derived(id ?? `sms-${utils.get_uuid().slice(0, 8)}`);
 const listbox_id = $derived(`${internal_id}-listbox`);
 // Parse shortcut string into modifier+key parts
 function parse_shortcut(shortcut) {
     const parts = shortcut.toLowerCase().split(`+`).map((part) => part.trim());
     const key = parts.pop() ?? ``;
-    return {
-        key,
-        ctrl: parts.includes(`ctrl`),
-        shift: parts.includes(`shift`),
-        alt: parts.includes(`alt`),
-        meta: parts.includes(`meta`) || parts.includes(`cmd`),
-    };
+    const ctrl = parts.includes(`ctrl`);
+    const shift = parts.includes(`shift`);
+    const alt = parts.includes(`alt`);
+    const meta = parts.includes(`meta`) || parts.includes(`cmd`);
+    return { key, ctrl, shift, alt, meta };
 }
 function matches_shortcut(event, shortcut) {
     if (!shortcut)
@@ -57,19 +57,22 @@ function matches_shortcut(event, shortcut) {
     const shift_matches = event.shiftKey === parsed.shift;
     const alt_matches = event.altKey === parsed.alt;
     const meta_matches = event.metaKey === parsed.meta;
-    return (key_matches && ctrl_matches && shift_matches && alt_matches && meta_matches);
+    return key_matches && ctrl_matches && shift_matches && alt_matches && meta_matches;
 }
+// Platform detection for keyboard shortcuts (Mac uses Cmd, others use Ctrl)
+const is_mac = typeof navigator !== `undefined` &&
+    /Mac|iPhone|iPad|iPod/.test(navigator.userAgent);
+const mod_key = is_mac ? `meta` : `ctrl`;
 // Default shortcuts
 const default_shortcuts = {
-    select_all: `ctrl+a`,
-    clear_all: `ctrl+shift+a`,
+    select_all: `${mod_key}+a`,
+    clear_all: `${mod_key}+shift+a`,
     open: null,
     close: null,
+    undo: `${mod_key}+z`,
+    redo: `${mod_key}+shift+z`,
 };
-const effective_shortcuts = $derived({
-    ...default_shortcuts,
-    ...shortcuts,
-});
+const effective_shortcuts = $derived({ ...default_shortcuts, ...shortcuts });
 // Extract loadOptions config into single derived object (supports both simple function and config object)
 const load_options_config = $derived.by(() => {
     if (!loadOptions)
@@ -94,8 +97,8 @@ function values_equal(val1, val2) {
     if (empty1 && empty2)
         return true;
     if (Array.isArray(val1) && Array.isArray(val2)) {
-        return val1.length === val2.length &&
-            val1.every((item, idx) => item === val2[idx]);
+        return (val1.length === val2.length &&
+            val1.every((item, idx) => item === val2[idx]));
     }
     return false;
 }
@@ -104,15 +107,17 @@ function values_equal(val1, val2) {
 // infinite loops with reactive wrappers that clone arrays. See issue #309.
 $effect.pre(() => {
     const new_value = maxSelect === 1 ? (selected[0] ?? null) : selected;
-    if (!values_equal(untrack(() => value), new_value))
+    if (!values_equal(untrack(() => value), new_value)) {
         value = new_value;
+    }
 });
 $effect.pre(() => {
     const new_selected = maxSelect === 1
         ? (value ? [value] : [])
         : (Array.isArray(value) ? value : []);
-    if (!values_equal(untrack(() => selected), new_selected))
+    if (!values_equal(untrack(() => selected), new_selected)) {
         selected = new_selected;
+    }
 });
 let wiggle = $state(false); // controls wiggle animation when user tries to exceed maxSelect
 let ignore_hover = $state(false); // ignore mouseover during keyboard navigation to prevent scroll-triggered hover
@@ -125,6 +130,107 @@ $effect(() => {
         return () => clearTimeout(timer);
     }
 });
+// History tracking for undo/redo
+const max_history = $derived(history === true
+    ? 50
+    : typeof history === `number` && Number.isFinite(history)
+        ? Math.max(0, Math.floor(history))
+        : 0);
+let history_stack = $state([]);
+let history_index = $state(-1); // -1 = no history yet
+let prev_selected = null; // null = uninitialized, sync on first run
+// Track changes to selected via $effect (catches internal + external changes)
+$effect(() => {
+    // Disabled when max_history is 0 (handles false, 0, negative, non-finite inputs)
+    const history_disabled = !(max_history > 0);
+    if (history_disabled) {
+        // Clear history when disabled so re-enabling starts fresh
+        history_stack = [];
+        history_index = -1;
+        // Don't read `selected` here to avoid creating unnecessary reactive dependency
+        prev_selected = null;
+        return;
+    }
+    // Initialize prev_selected on first run to avoid phantom undo from [] → initial selection
+    if (prev_selected === null) {
+        prev_selected = [...selected];
+        return;
+    }
+    // Check if actually changed (avoid duplicates from reactive updates)
+    if (values_equal(selected, prev_selected))
+        return;
+    // On first change, push initial state first
+    if (history_stack.length === 0) {
+        history_stack = [[...prev_selected]];
+        history_index = 0;
+    }
+    // Truncate any redo states
+    if (history_index < history_stack.length - 1) {
+        history_stack = history_stack.slice(0, history_index + 1);
+    }
+    // Push new state
+    history_stack = [...history_stack, [...selected]];
+    history_index = history_stack.length - 1;
+    // Trim to max size (remove oldest)
+    if (history_stack.length > max_history) {
+        const excess = history_stack.length - max_history;
+        history_stack = history_stack.slice(excess);
+        history_index = Math.max(0, history_index - excess);
+    }
+    prev_selected = [...selected];
+});
+// Derived canUndo/canRedo (update bindable props reactively)
+$effect(() => {
+    canUndo = max_history > 0 && !disabled && history_index > 0;
+    canRedo = max_history > 0 && !disabled && history_index < history_stack.length - 1;
+});
+// Undo: restore previous state
+undo = () => {
+    if (max_history <= 0 || disabled || history_index <= 0)
+        return false;
+    const previous = [...selected];
+    history_index--;
+    selected = [...history_stack[history_index]];
+    prev_selected = [...selected]; // sync tracker to prevent $effect re-recording
+    onundo?.({ previous, current: selected });
+    return true;
+};
+// Redo: restore next state
+redo = () => {
+    if (max_history <= 0 || disabled || history_index >= history_stack.length - 1) {
+        return false;
+    }
+    const previous = [...selected];
+    history_index++;
+    selected = [...history_stack[history_index]];
+    prev_selected = [...selected]; // sync tracker to prevent $effect re-recording
+    onredo?.({ previous, current: selected });
+    return true;
+};
+// Debounced onsearch event - fires 150ms after search text stops changing
+let search_debounce_timer = null;
+let search_initialized = false;
+$effect(() => {
+    const current_search = searchText;
+    // Skip initial mount - only fire on actual user input
+    if (!search_initialized) {
+        search_initialized = true;
+        return;
+    }
+    if (!onsearch)
+        return; // cleanup handles any pending timer
+    search_debounce_timer = setTimeout(() => {
+        // Optional chaining in case onsearch is removed while timer is pending
+        onsearch?.({
+            searchText: current_search,
+            matchingCount: matchingOptions.length,
+        });
+    }, 150);
+    return () => {
+        if (search_debounce_timer)
+            clearTimeout(search_debounce_timer);
+    };
+});
 // Internal state for loadOptions feature (null = never loaded)
 let loaded_options = $state([]);
 let load_options_has_more = $state(true);
@@ -134,13 +240,13 @@ let debounce_timer = null;
 let effective_options = $derived(loadOptions ? loaded_options : (options ?? []));
 // Cache selected keys and labels to avoid repeated .map() calls
 let selected_keys = $derived(selected.map(key));
-let selected_labels = $derived(selected.map(get_label));
+let selected_labels = $derived(selected.map(utils.get_label));
 // Sets for O(1) lookups (used in template, has_user_msg, group_header_state, batch operations)
 let selected_keys_set = $derived(new Set(selected_keys));
 let selected_labels_set = $derived(new Set(selected_labels));
 // Memoized Set of disabled option keys for O(1) lookups in large option sets
 let disabled_option_keys = $derived(new Set(effective_options
-    .filter((opt) => is_object(opt) && opt.disabled)
+    .filter((opt) => utils.is_object(opt) && opt.disabled)
     .map(key)));
 // Check if an option is disabled (uses memoized Set for O(1) lookup)
 const is_disabled = (opt) => disabled_option_keys.has(key(opt));
@@ -151,7 +257,7 @@ let grouped_options = $derived.by(() => {
     const groups_map = new SvelteMap();
     const ungrouped = [];
     for (const opt of matchingOptions) {
-        if (has_group(opt)) {
+        if (utils.has_group(opt)) {
             const existing = groups_map.get(opt.group);
             if (existing)
                 existing.push(opt);
@@ -179,7 +285,11 @@ let grouped_options = $derived.by(() => {
     }
     if (ungrouped.length === 0)
         return grouped;
-    const ungrouped_entry = { group: null, options: ungrouped, collapsed: false };
+    const ungrouped_entry = {
+        group: null,
+        options: ungrouped,
+        collapsed: false,
+    };
     return ungroupedPosition === `first`
         ? [ungrouped_entry, ...grouped]
         : [...grouped, ungrouped_entry];
@@ -248,8 +358,9 @@ function expand_groups(groups_to_expand) {
     if (groups_to_expand.length === 0)
         return;
     update_collapsed_groups(`delete`, groups_to_expand);
-    for (const group of groups_to_expand)
+    for (const group of groups_to_expand) {
         ongroupToggle?.({ group, collapsed: false });
+    }
 }
 // Get names of collapsed groups that have matching options
 const get_collapsed_with_matches = () => grouped_options.flatMap(({ group, collapsed, options: opts }) => group && collapsed && opts.length > 0 ? [group] : []);
@@ -260,61 +371,65 @@ $effect(() => {
     }
 });
 // Normalize placeholder prop (supports string or { text, persistent } object)
-const placeholder_text = $derived(typeof placeholder === `string` ? placeholder : placeholder?.text ?? null);
+const placeholder_text = $derived(typeof placeholder === `string` ? placeholder : (placeholder?.text ?? null));
 const placeholder_persistent = $derived(typeof placeholder === `object` && placeholder?.persistent === true);
 // Helper to sort selected options (used by add() and select_all())
 function sort_selected(items) {
     if (sortSelected === true) {
-        return items.toSorted((op1, op2) => `${get_label(op1)}`.localeCompare(`${get_label(op2)}`));
+        return items.toSorted((op1, op2) => `${utils.get_label(op1)}`.localeCompare(`${utils.get_label(op2)}`));
     }
     else if (typeof sortSelected === `function`) {
         return items.toSorted(sortSelected);
     }
     return items;
 }
-if (!loadOptions && !((options?.length ?? 0) > 0)) {
-    if (allowUserOptions || loading || disabled || allowEmpty) {
-        options = []; // initializing as array avoids errors when component mounts
-    }
-    else {
-        // error on empty options if user is not allowed to create custom options and loading is false
-        // and component is not disabled and allowEmpty is false
-        console.error(`MultiSelect: received no options`);
+untrack(() => {
+    if (!loadOptions && !((options?.length ?? 0) > 0)) {
+        if (allowUserOptions || loading || disabled || allowEmpty) {
+            options = []; // initializing as array avoids errors when component mounts
+        }
+        else {
+            // error on empty options if user is not allowed to create custom options and loading is false
+            // and component is not disabled and allowEmpty is false
+            console.error(`MultiSelect: received no options`);
+        }
     }
-}
+});
 if (maxSelect !== null && maxSelect < 1) {
     console.error(`MultiSelect: maxSelect must be null or positive integer, got ${maxSelect}`);
 }
 if (!Array.isArray(selected)) {
     console.error(`MultiSelect: selected prop should always be an array, got ${selected}`);
 }
-if (maxSelect && typeof required === `number` && required > maxSelect) {
-    console.error(`MultiSelect: maxSelect=${maxSelect} < required=${required}, makes it impossible for users to submit a valid form`);
-}
-if (parseLabelsAsHtml && allowUserOptions) {
-    console.warn(`MultiSelect: don't combine parseLabelsAsHtml and allowUserOptions. It's susceptible to XSS attacks!`);
-}
-if (sortSelected && selectedOptionsDraggable) {
-    console.warn(`MultiSelect: sortSelected and selectedOptionsDraggable should not be combined as any ` +
-        `user re-orderings of selected options will be undone by sortSelected on component re-renders.`);
-}
-if (allowUserOptions && !createOptionMsg && createOptionMsg !== null) {
-    console.error(`MultiSelect: allowUserOptions=${allowUserOptions} but createOptionMsg=${createOptionMsg} is falsy. ` +
-        `This prevents the "Add option" <span> from showing up, resulting in a confusing user experience.`);
-}
-if (maxOptions &&
-    (typeof maxOptions != `number` || maxOptions < 0 || maxOptions % 1 != 0)) {
-    console.error(`MultiSelect: maxOptions must be undefined or a positive integer, got ${maxOptions}`);
-}
+$effect(() => {
+    if (maxSelect && typeof required === `number` && required > maxSelect) {
+        console.error(`MultiSelect: maxSelect=${maxSelect} < required=${required}, makes it impossible for users to submit a valid form`);
+    }
+    if (parseLabelsAsHtml && allowUserOptions) {
+        console.warn(`MultiSelect: don't combine parseLabelsAsHtml and allowUserOptions. It's susceptible to XSS attacks!`);
+    }
+    if (sortSelected && selectedOptionsDraggable) {
+        console.warn(`MultiSelect: sortSelected and selectedOptionsDraggable should not be combined as any ` +
+            `user re-orderings of selected options will be undone by sortSelected on component re-renders.`);
+    }
+    if (allowUserOptions && !createOptionMsg && createOptionMsg !== null) {
+        console.error(`MultiSelect: allowUserOptions=${allowUserOptions} but createOptionMsg=${createOptionMsg} is falsy. ` +
+            `This prevents the "Add option" <span> from showing up, resulting in a confusing user experience.`);
+    }
+    if (maxOptions &&
+        (typeof maxOptions != `number` || maxOptions < 0 || maxOptions % 1 != 0)) {
+        console.error(`MultiSelect: maxOptions must be undefined or a positive integer, got ${maxOptions}`);
+    }
+});
 let option_msg_is_active = $state(false); // controls active state of <li>{createOptionMsg}</li>
 let window_width = $state(0);
 // Check if option matches search text (label or optionally group name)
 const matches_search = (opt, search) => {
     if (filterFunc(opt, search))
         return true;
-    if (searchMatchesGroups && search && has_group(opt)) {
+    if (searchMatchesGroups && search && utils.has_group(opt)) {
         return fuzzy
-            ? fuzzy_match(search, opt.group)
+            ? utils.fuzzy_match(search, opt.group)
             : opt.group.toLowerCase().includes(search.toLowerCase());
     }
     return false;
@@ -363,10 +478,19 @@ function add(option_to_add, event) {
     event.stopPropagation();
     if (maxSelect !== null && selected.length >= maxSelect)
         wiggle = true;
-    if (!isNaN(Number(option_to_add)) && typeof selected_labels[0] === `number`) {
+    if (!isNaN(Number(option_to_add)) &&
+        typeof selected_labels[0] === `number`) {
         option_to_add = Number(option_to_add); // convert to number if possible
     }
     const is_duplicate = selected_keys_set.has(key(option_to_add));
+    const max_reached = maxSelect !== null && maxSelect !== 1 &&
+        selected.length >= maxSelect;
+    // Fire events for blocked add attempts
+    if (max_reached) {
+        onmaxreached?.({ selected, maxSelect, attemptedOption: option_to_add });
+    }
+    if (is_duplicate && !duplicates)
+        onduplicate?.({ option: option_to_add });
     if ((maxSelect === null || maxSelect === 1 || selected.length < maxSelect) &&
         (duplicates || !is_duplicate)) {
         if (!effective_options.includes(option_to_add) && // first check if we find option in the options list
@@ -415,7 +539,7 @@ function add(option_to_add, event) {
         }
         clear_validity();
         handle_dropdown_after_select(event);
-        last_action = { type: `add`, label: `${get_label(option_to_add)}` };
+        last_action = { type: `add`, label: `${utils.get_label(option_to_add)}` };
         onadd?.({ option: option_to_add });
         onchange?.({ option: option_to_add, type: `add` });
     }
@@ -440,7 +564,7 @@ function remove(option_to_drop, event) {
     }
     selected = selected.filter((_, remove_idx) => remove_idx !== idx);
     clear_validity();
-    last_action = { type: `remove`, label: `${get_label(option_removed)}` };
+    last_action = { type: `remove`, label: `${utils.get_label(option_removed)}` };
     onremove?.({ option: option_removed });
     onchange?.({ option: option_removed, type: `remove` });
 }
@@ -470,7 +594,8 @@ function handle_dropdown_after_select(event) {
     const reached_max = selected.length >= (maxSelect ?? Infinity);
     const should_close = closeDropdownOnSelect === true ||
         closeDropdownOnSelect === `retain-focus` ||
-        (closeDropdownOnSelect === `if-mobile` && window_width &&
+        (closeDropdownOnSelect === `if-mobile` &&
+            window_width &&
             window_width < breakpoint);
     if (reached_max || should_close) {
         close_dropdown(event, closeDropdownOnSelect === `retain-focus`);
@@ -479,19 +604,24 @@ function handle_dropdown_after_select(event) {
         input?.focus();
 }
 // Check if a user message (create option, duplicate warning, no match) is visible
-const has_user_msg = $derived(searchText.length > 0 && Boolean((allowUserOptions && createOptionMsg) ||
-    (!duplicates && selected_labels_set.has(searchText)) ||
-    (navigable_options.length === 0 && noMatchingOptionsMsg)));
+const has_user_msg = $derived(searchText.length > 0 &&
+    Boolean((allowUserOptions && createOptionMsg) ||
+        (!duplicates && selected_labels_set.has(searchText)) ||
+        (navigable_options.length === 0 && noMatchingOptionsMsg)));
 // Handle arrow key navigation through options (uses navigable_options to skip collapsed groups)
 async function handle_arrow_navigation(direction) {
     ignore_hover = true;
     // Auto-expand collapsed groups when keyboard navigating
-    if (keyboardExpandsCollapsedGroups && collapsibleGroups && collapsedGroups.size > 0) {
+    if (keyboardExpandsCollapsedGroups &&
+        collapsibleGroups &&
+        collapsedGroups.size > 0) {
         expand_groups(get_collapsed_with_matches());
         await tick();
     }
     // toggle user message when no options match but user can create
-    if (allowUserOptions && !navigable_options.length && searchText.length > 0) {
+    if (allowUserOptions &&
+        !navigable_options.length &&
+        searchText.length > 0) {
         option_msg_is_active = !option_msg_is_active;
         return;
     }
@@ -503,17 +633,26 @@ async function handle_arrow_navigation(direction) {
     }
     else {
         const total = navigable_options.length + (has_user_msg ? 1 : 0);
+        // Guard against division by zero (can happen if options filtered away before effect resets activeIndex)
+        if (total === 0) {
+            activeIndex = null;
+            return;
+        }
         activeIndex = (activeIndex + direction + total) % total; // +total handles negative mod
     }
     // update active state based on new index
     option_msg_is_active = has_user_msg && activeIndex === navigable_options.length;
     activeOption = option_msg_is_active
         ? null
-        : navigable_options[activeIndex] ?? null;
+        : (navigable_options[activeIndex] ?? null);
     if (autoScroll) {
         await tick();
-        document.querySelector(`ul.options > li.active`)?.scrollIntoViewIfNeeded?.();
+        document
+            .querySelector(`ul.options > li.active`)
+            ?.scrollIntoViewIfNeeded?.();
     }
+    // Fire onactivate for keyboard navigation only (not mouse hover)
+    onactivate?.({ option: activeOption, index: activeIndex });
 }
 // handle all keyboard events this component receives
 async function handle_keydown(event) {
@@ -544,6 +683,16 @@ async function handle_keydown(event) {
                 searchText = ``;
             },
         },
+        {
+            key: `undo`,
+            condition: () => !!canUndo,
+            action: () => undo?.(),
+        },
+        {
+            key: `redo`,
+            condition: () => !!canRedo,
+            action: () => redo?.(),
+        },
     ];
     for (const { key, condition, action } of shortcut_actions) {
         if (matches_shortcut(event, effective_shortcuts[key]) && condition()) {
@@ -616,7 +765,10 @@ function remove_all(event) {
     // Only fire events if something was actually removed
     if (removed_options.length > 0) {
         searchText = ``; // always clear on remove all (resetFilterOnAdd only applies to add operations)
-        last_action = { type: `removeAll`, label: `${removed_options.length} options` };
+        last_action = {
+            type: `removeAll`,
+            label: `${removed_options.length} options`,
+        };
         onremoveAll?.({ options: removed_options });
         onchange?.({ options: selected, type: `removeAll` });
     }
@@ -699,8 +851,9 @@ function on_click_outside(event) {
     if (outerDiv.contains(target))
         return;
     // If portal is active, also check if click is inside the portalled options dropdown
-    if (portal_params?.active && ul_options && ul_options.contains(target))
+    if (portal_params?.active && ul_options && ul_options.contains(target)) {
         return;
+    }
     // Click is outside both the main component and any portalled dropdown
     close_dropdown(event);
 }
@@ -812,8 +965,9 @@ function portal(node, params) {
                 target_node = params.target_node;
                 render_in_place = typeof window === `undefined` ||
                     !document.body.contains(node);
-                if (open && !render_in_place && target_node)
+                if (open && !render_in_place && target_node) {
                     tick().then(update_position);
+                }
                 else if (!open || !target_node)
                     node.hidden = true;
             },
@@ -828,7 +982,8 @@ function portal(node, params) {
 }
 // Dynamic options loading - captures search at call time to avoid race conditions
 async function load_dynamic_options(reset) {
-    if (!load_options_config || load_options_loading ||
+    if (!load_options_config ||
+        load_options_loading ||
         (!reset && !load_options_has_more)) {
         return;
     }
@@ -889,11 +1044,13 @@ $effect(() => {
     };
 });
 function handle_options_scroll(event) {
-    if (!load_options_config || load_options_loading || !load_options_has_more)
+    if (!load_options_config || load_options_loading || !load_options_has_more) {
         return;
+    }
     const { scrollTop, scrollHeight, clientHeight } = event.target;
-    if (scrollHeight - scrollTop - clientHeight <= 100)
+    if (scrollHeight - scrollTop - clientHeight <= 100) {
         load_dynamic_options(false);
+    }
 }
 </script>
 
@@ -957,11 +1114,9 @@ function handle_options_scroll(event) {
     style={ulSelectedStyle}
   >
     {#each selected as option, idx (duplicates ? `${key(option)}-${idx}` : key(option))}
-      {@const selectedOptionStyle =
-        [get_style(option, `selected`), liSelectedStyle].filter(Boolean).join(
-          ` `,
-        ) ||
-        null}
+      {@const selectedOptionStyle = [utils.get_style(option, `selected`), liSelectedStyle]
+        .filter(Boolean)
+        .join(` `) || null}
       <li
         class={liSelectedClass}
         role="option"
@@ -979,26 +1134,20 @@ function handle_options_scroll(event) {
         onmouseup={(event) => event.stopPropagation()}
       >
         {#if selectedItem}
-          {@render selectedItem({
-          option,
-          idx,
-        })}
+          {@render selectedItem({ option, idx })}
         {:else if children}
-          {@render children({
-          option,
-          idx,
-        })}
+          {@render children({ option, idx })}
         {:else if parseLabelsAsHtml}
-          {@html get_label(option)}
+          {@html utils.get_label(option)}
         {:else}
-          {get_label(option)}
+          {utils.get_label(option)}
         {/if}
         {#if !disabled && can_remove}
           <button
             onclick={(event) => remove(option, event)}
             onkeydown={if_enter_or_space((event) => remove(option, event))}
             type="button"
-            title="{removeBtnTitle} {get_label(option)}"
+            title="{removeBtnTitle} {utils.get_label(option)}"
             class="remove"
           >
             {#if removeIcon}
@@ -1145,8 +1294,9 @@ function handle_options_scroll(event) {
         (group_name ?? `ungrouped-${group_idx}`)
       }
         {#if group_name !== null}
-          {@const { all_selected, selected_count } = group_header_state.get(group_name) ??
-        { all_selected: false, selected_count: 0 }}
+          {@const { all_selected, selected_count } = group_header_state.get(
+        group_name,
+      ) ?? { all_selected: false, selected_count: 0 }}
           {@const handle_toggle = () =>
         collapsibleGroups && toggle_group_collapsed(group_name)}
           {@const handle_group_select = (event: Event) =>
@@ -1210,14 +1360,12 @@ function handle_options_scroll(event) {
         title = null,
         selectedTitle = null,
         disabledTitle = defaultDisabledTitle,
-      } = is_object(option_item) ? option_item : { label: option_item }}
+      } = utils.is_object(option_item) ? option_item : { label: option_item }}
             {@const active = activeIndex === flat_idx && flat_idx >= 0}
             {@const selected = is_selected(label)}
-            {@const optionStyle =
-        [get_style(option_item, `option`), liOptionStyle].filter(Boolean).join(
-          ` `,
-        ) ||
-        null}
+            {@const optionStyle = [utils.get_style(option_item, `option`), liOptionStyle]
+        .filter(Boolean)
+        .join(` `) || null}
             {#if is_option_visible(flat_idx)}
               <li
                 id="{internal_id}-opt-{flat_idx}"
@@ -1247,24 +1395,18 @@ function handle_options_scroll(event) {
                     type="checkbox"
                     class="option-checkbox"
                     checked={selected}
-                    aria-label="Toggle {get_label(option_item)}"
+                    aria-label="Toggle {utils.get_label(option_item)}"
                     tabindex="-1"
                   />
                 {/if}
                 {#if option}
-                  {@render option({
-          option: option_item,
-          idx: flat_idx,
-        })}
+                  {@render option({ option: option_item, idx: flat_idx })}
                 {:else if children}
-                  {@render children({
-          option: option_item,
-          idx: flat_idx,
-        })}
+                  {@render children({ option: option_item, idx: flat_idx })}
                 {:else if parseLabelsAsHtml}
-                  {@html get_label(option_item)}
+                  {@html utils.get_label(option_item)}
                 {:else}
-                  {get_label(option_item)}
+                  {utils.get_label(option_item)}
                 {/if}
               </li>
             {/if}
@@ -1323,7 +1465,11 @@ function handle_options_scroll(event) {
         {/if}
       {/if}
       {#if loadOptions && load_options_loading}
-        <li class="loading-more" role="status" aria-label="Loading more options">
+        <li
+          class="loading-more"
+          role="status"
+          aria-label="Loading more options"
+        >
           <CircleSpinner />
         </li>
       {/if}
@@ -1359,7 +1505,9 @@ function handle_options_scroll(event) {
     border: 0;
   }
 
-  :is(div.multiselect) {
+  /* Use :where() for elements with user-overridable class props (outerDivClass, ulSelectedClass, liSelectedClass)
+     so user-provided classes take precedence. See: https://github.com/janosh/svelte-multiselect/issues/380 */
+  :where(div.multiselect) {
     position: relative;
     align-items: center;
     display: flex;
@@ -1376,27 +1524,30 @@ function handle_options_scroll(event) {
     min-height: var(--sms-min-height, 22pt);
     margin: var(--sms-margin);
   }
-  :is(div.multiselect.open) {
+  :where(div.multiselect.open) {
     /* increase z-index when open to ensure the dropdown of one <MultiSelect />
     displays above that of another slightly below it on the page */
     z-index: var(--sms-open-z-index, 4);
   }
-  :is(div.multiselect:focus-within) {
-    border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue));
+  :where(div.multiselect:focus-within) {
+    border: var(
+      --sms-focus-border,
+      1pt solid var(--sms-active-color, cornflowerblue)
+    );
   }
-  :is(div.multiselect.disabled) {
+  :where(div.multiselect.disabled) {
     background: var(--sms-disabled-bg, light-dark(lightgray, #444));
     cursor: not-allowed;
   }
 
-  :is(div.multiselect > ul.selected) {
+  :where(div.multiselect > ul.selected) {
     display: flex;
     flex: 1;
     padding: 0;
     margin: 0;
     flex-wrap: wrap;
   }
-  :is(div.multiselect > ul.selected > li) {
+  :where(div.multiselect > ul.selected > li) {
     align-items: center;
     border-radius: 3pt;
     display: flex;
@@ -1411,13 +1562,16 @@ function handle_options_scroll(event) {
     padding: var(--sms-selected-li-padding, 1pt 5pt);
     color: var(--sms-selected-text-color, var(--sms-text-color));
   }
-  :is(div.multiselect > ul.selected > li[draggable='true']) {
+  :where(div.multiselect > ul.selected > li[draggable='true']) {
     cursor: grab;
   }
-  :is(div.multiselect > ul.selected > li.active) {
+  :where(div.multiselect > ul.selected > li.active) {
     background: var(
       --sms-li-active-bg,
-      var(--sms-active-color, light-dark(rgba(0, 0, 0, 0.15), rgba(255, 255, 255, 0.15)))
+      var(
+        --sms-active-color,
+        light-dark(rgba(0, 0, 0, 0.15), rgba(255, 255, 255, 0.15))
+      )
     );
   }
   :is(div.multiselect button) {
@@ -1448,7 +1602,7 @@ function handle_options_scroll(event) {
     margin: auto 0; /* CSS reset */
     padding: 0; /* CSS reset */
   }
-  :is(div.multiselect > ul.selected > input) {
+  :where(div.multiselect > ul.selected > input) {
     border: none;
     outline: none;
     background: none;
@@ -1462,7 +1616,7 @@ function handle_options_scroll(event) {
   }
 
   /* When options are selected, placeholder is hidden in which case we minimize input width to avoid adding unnecessary width to div.multiselect */
-  :is(div.multiselect > ul.selected > input:not(:placeholder-shown)) {
+  :where(div.multiselect > ul.selected > input:not(:placeholder-shown)) {
     min-width: 1px; /* Minimal width to remain interactive */
   }
 
@@ -1483,7 +1637,8 @@ function handle_options_scroll(event) {
     pointer-events: none;
   }
 
-  ul.options {
+  /* Use :where() for ul.options elements with class props (ulOptionsClass, liOptionClass, liUserMsgClass) */
+  :where(ul.options) {
     list-style: none;
     /* top, left, width, position are managed by portal when active */
     /* but provide defaults for non-portaled or initial state */
@@ -1493,10 +1648,8 @@ function handle_options_scroll(event) {
     width: 100%;
     /* Default z-index if not portaled/overridden by portal */
     z-index: var(--sms-options-z-index, 3);
-
     overflow: auto;
-    transition: all
-      0.2s; /* Consider if this transition is desirable with portal positioning */
+    transition: all 0.2s; /* is this transition is desirable with portal positioning? */
     box-sizing: border-box;
     background: var(--sms-options-bg, light-dark(#fafafa, #1a1a1a));
     max-height: var(--sms-options-max-height, 50vh);
@@ -1511,24 +1664,24 @@ function handle_options_scroll(event) {
     padding: var(--sms-options-padding);
     margin: var(--sms-options-margin, 6pt 0 0 0);
   }
-  ul.options.hidden {
+  :where(ul.options.hidden) {
     visibility: hidden;
     opacity: 0;
     transform: translateY(50px);
     pointer-events: none;
   }
-  ul.options > li {
+  :where(ul.options > li) {
     padding: 3pt 1ex;
     cursor: pointer;
     scroll-margin: var(--sms-options-scroll-margin, 100px);
     border-left: 3px solid transparent;
   }
-  ul.options .user-msg {
+  :where(ul.options .user-msg) {
     /* block needed so vertical padding applies to span */
     display: block;
     padding: 3pt 2ex;
   }
-  ul.options > li.selected {
+  :where(ul.options > li.selected) {
     background: var(
       --sms-li-selected-plain-bg,
       light-dark(rgba(0, 123, 255, 0.1), rgba(100, 180, 255, 0.2))
@@ -1538,26 +1691,29 @@ function handle_options_scroll(event) {
       3px solid var(--sms-active-color, cornflowerblue)
     );
   }
-  ul.options > li.active {
+  :where(ul.options > li.active) {
     background: var(
       --sms-li-active-bg,
-      var(--sms-active-color, light-dark(rgba(0, 0, 0, 0.15), rgba(255, 255, 255, 0.15)))
+      var(
+        --sms-active-color,
+        light-dark(rgba(0, 0, 0, 0.15), rgba(255, 255, 255, 0.15))
+      )
     );
   }
-  ul.options > li.disabled {
+  :where(ul.options > li.disabled) {
     cursor: not-allowed;
     background: var(--sms-li-disabled-bg, light-dark(#f5f5f6, #2a2a2a));
     color: var(--sms-li-disabled-text, light-dark(#b8b8b8, #666));
   }
-  /* Checkbox styling for keepSelectedInDropdown='checkboxes' mode */
-  ul.options > li > input.option-checkbox {
+  /* Checkbox styling for keepSelectedInDropdown='checkboxes' mode - internal, no class prop */
+  :is(ul.options > li > input.option-checkbox) {
     width: 16px;
     height: 16px;
     margin-right: 6px;
     accent-color: var(--sms-active-color, cornflowerblue);
   }
-  /* Select all option styling */
-  ul.options > li.select-all {
+  /* Select all option styling - has liSelectAllClass prop */
+  :where(ul.options > li.select-all) {
     border-bottom: var(
       --sms-select-all-border-bottom,
       1px solid light-dark(lightgray, #555)
@@ -1567,7 +1723,7 @@ function handle_options_scroll(event) {
     background: var(--sms-select-all-bg, transparent);
     margin-bottom: var(--sms-select-all-margin-bottom, 2pt);
   }
-  ul.options > li.select-all:hover {
+  :where(ul.options > li.select-all:hover) {
     background: var(
       --sms-select-all-hover-bg,
       var(
@@ -1579,8 +1735,8 @@ function handle_options_scroll(event) {
       )
     );
   }
-  /* Group header styling */
-  ul.options > li.group-header {
+  /* Group header styling - has liGroupHeaderClass prop */
+  :where(ul.options > li.group-header) {
     display: flex;
     align-items: center;
     font-weight: var(--sms-group-header-font-weight, 600);
@@ -1593,30 +1749,34 @@ function handle_options_scroll(event) {
     text-transform: var(--sms-group-header-text-transform, uppercase);
     letter-spacing: var(--sms-group-header-letter-spacing, 0.5px);
   }
-  ul.options > li.group-header:not(:first-child) {
+  :where(ul.options > li.group-header:not(:first-child)) {
     margin-top: var(--sms-group-header-margin-top, 4pt);
-    border-top: var(--sms-group-header-border-top, 1px solid light-dark(#eee, #333));
+    border-top: var(
+      --sms-group-header-border-top,
+      1px solid light-dark(#eee, #333)
+    );
   }
-  ul.options > li.group-header.collapsible {
+  :where(ul.options > li.group-header.collapsible) {
     cursor: pointer;
   }
-  ul.options > li.group-header.collapsible:hover {
+  :where(ul.options > li.group-header.collapsible:hover) {
     background: var(
       --sms-group-header-hover-bg,
       light-dark(rgba(0, 0, 0, 0.05), rgba(255, 255, 255, 0.05))
     );
   }
-  ul.options > li.group-header .group-label {
+  /* Internal elements without class props - keep :is() for specificity */
+  :is(ul.options > li.group-header .group-label) {
     flex: 1;
   }
-  ul.options > li.group-header .group-count {
+  :is(ul.options > li.group-header .group-count) {
     opacity: 0.6;
     font-size: 0.9em;
     font-weight: normal;
     margin-left: 4pt;
   }
   /* Sticky group headers when enabled */
-  ul.options > li.group-header.sticky {
+  :where(ul.options > li.group-header.sticky) {
     position: sticky;
     top: 0;
     z-index: 1;
@@ -1626,17 +1786,20 @@ function handle_options_scroll(event) {
     );
   }
   /* Indent grouped options for visual hierarchy */
-  ul.options > li:not(.group-header):not(.select-all):not(.user-msg):not(.loading-more) {
+  :where(
+    ul.options > li:not(.group-header):not(.select-all):not(.user-msg):not(.loading-more)
+  ) {
     padding-left: var(
       --sms-group-item-padding-left,
       var(--sms-group-option-indent, 1.5ex)
     );
   }
-  /* Collapse/expand animation for group chevron icon */
-  ul.options > li.group-header :global(svg) {
+  /* Collapse/expand animation for group chevron icon - internal, keep :is() for specificity */
+  :is(ul.options > li.group-header) :global(svg) {
     transition: transform var(--sms-group-collapse-duration, 0.15s) ease-out;
   }
-  ul.options > li.group-header button.group-select-all {
+  /* Keep :is() for internal buttons without class props */
+  :is(ul.options > li.group-header button.group-select-all) {
     font-size: 0.9em;
     font-weight: normal;
     text-transform: none;
@@ -1649,23 +1812,23 @@ function handle_options_scroll(event) {
     border-radius: 3pt;
     aspect-ratio: auto; /* override global button aspect-ratio: 1 */
   }
-  ul.options > li.group-header button.group-select-all:hover {
+  :is(ul.options > li.group-header button.group-select-all:hover) {
     background: var(
       --sms-group-select-all-hover-bg,
       light-dark(rgba(0, 0, 0, 0.1), rgba(255, 255, 255, 0.1))
     );
   }
-  ul.options > li.group-header button.group-select-all.deselect {
+  :is(ul.options > li.group-header button.group-select-all.deselect) {
     color: var(--sms-group-deselect-color, light-dark(#c44, #f77));
   }
-  :is(span.max-select-msg) {
+  :where(span.max-select-msg) {
     padding: 0 3pt;
   }
   ::highlight(sms-search-matches) {
     color: light-dark(#1a8870, mediumaquamarine);
   }
-  /* Loading more indicator for infinite scrolling */
-  ul.options > li.loading-more {
+  /* Loading more indicator for infinite scrolling - internal, no class prop */
+  :is(ul.options > li.loading-more) {
     display: flex;
     justify-content: center;
     align-items: center;