svelte-5-select 1.0.2 → 2.0.0

package/dist/use-hover.svelte.d.ts

@@ -1,11 +1,7 @@
-import type { HoverContext, SelectItem } from './types';
-export declare function useHover(context: HoverContext): {
-    computeNextIndex: (filteredItems: SelectItem[], fromIndex: number, increment: number) => number;
+import type { ItemLike, SelectItem, SelectState } from './types';
+export declare function useHover<Item extends ItemLike = SelectItem>(state: SelectState<Item>): {
     setHoverIndex: (increment: number) => void;
-    setValueIndexAsHoverIndex: () => void;
-    checkHoverSelectable: (startingIndex?: number, ignoreGroup?: boolean) => void;
-    getFirstSelectableIndex: () => number;
-    isItemActive: (item: SelectItem, val: SelectItem | SelectItem[] | null | undefined, itemId: string) => boolean | undefined;
+    isItemActive: (item: SelectItem) => boolean;
     isItemSelectable: (item: SelectItem) => boolean;
     handleHover: (i: number) => void;
     handleListScroll: () => void;

package/dist/use-hover.svelte.js

@@ -1,7 +1,10 @@
-import { areItemsEqual, isItemSelectableCheck } from './utils';
-export function useHover(context) {
+import { untrack } from 'svelte';
+import { areItemsEqual, getItemProperty, isItemSelectableCheck, normalizeItem } from './utils';
+export function useHover(state) {
     function computeNextIndex(filteredItems, fromIndex, increment) {
-        let selectableFilteredItems = filteredItems.filter((item) => !Object.hasOwn(item, 'selectable') || item.selectable === true);
+        // Same predicate as click/Enter selection: arrow keys must be able to
+        // reach every item the user can otherwise select
+        const selectableFilteredItems = filteredItems.filter((item) => isItemSelectableCheck(item));
         if (selectableFilteredItems.length === 0) {
             return 0;
         }
@@ -9,7 +12,7 @@ export function useHover(context) {
         const isCurrentSelectable = isItemSelectableCheck(currentItem);
         let currentSelectableIndex;
         if (isCurrentSelectable) {
-            currentSelectableIndex = selectableFilteredItems.findIndex(item => item === currentItem);
+            currentSelectableIndex = selectableFilteredItems.findIndex((item) => item === currentItem);
         }
         else {
             currentSelectableIndex = increment > 0 ? -1 : selectableFilteredItems.length;
@@ -19,40 +22,40 @@ export function useHover(context) {
             newSelectableIndex = (currentSelectableIndex + 1) % selectableFilteredItems.length;
         }
         else {
-            newSelectableIndex = (currentSelectableIndex - 1 + selectableFilteredItems.length) % selectableFilteredItems.length;
+            newSelectableIndex =
+                (currentSelectableIndex - 1 + selectableFilteredItems.length) % selectableFilteredItems.length;
         }
         const newItem = selectableFilteredItems[newSelectableIndex];
-        return filteredItems.findIndex(item => item === newItem);
+        return filteredItems.findIndex((item) => item === newItem);
     }
     function setHoverIndex(increment) {
-        const { filteredItems, hoverItemIndex } = context.getState();
-        context.setHoverItemIndex(computeNextIndex(filteredItems, hoverItemIndex, increment));
+        const { filteredItems, hoverItemIndex } = state;
+        state.hoverItemIndex = computeNextIndex(filteredItems, hoverItemIndex, increment);
     }
     function setValueIndexAsHoverIndex() {
-        const { value, filteredItems, itemId } = context.getState();
-        const normalizedValue = !value ? null : typeof value === 'string' ? { value, label: value } : value;
+        const { normalizedValue, filteredItems, itemId } = state;
         if (!normalizedValue || Array.isArray(normalizedValue))
             return;
-        const singleValue = normalizedValue;
-        const valueIndex = filteredItems.findIndex((i) => {
-            return i[itemId] === singleValue[itemId];
-        });
+        const valueIndex = filteredItems.findIndex((item) => getItemProperty(item, itemId) === getItemProperty(normalizedValue, itemId));
         checkHoverSelectable(valueIndex, true);
     }
-    function checkHoverSelectable(startingIndex = 0, ignoreGroup) {
-        const { groupBy, filteredItems } = context.getState();
+    function checkHoverSelectable(startingIndex = 0, trustIndex) {
+        const { filteredItems } = state;
         const idx = startingIndex < 0 ? 0 : startingIndex;
-        if (!ignoreGroup && groupBy && filteredItems[idx] && !filteredItems[idx].selectable) {
+        // Same predicate as click/Enter selection (a missing `selectable` key
+        // means selectable), and not gated on groupBy: a plain list can start
+        // with a non-selectable item too
+        if (!trustIndex && filteredItems[idx] && !isItemSelectableCheck(filteredItems[idx])) {
             // Compute the final index without intermediate state writes
-            context.setHoverItemIndex(computeNextIndex(filteredItems, idx, 1));
+            state.hoverItemIndex = computeNextIndex(filteredItems, idx, 1);
         }
         else {
-            context.setHoverItemIndex(idx);
+            state.hoverItemIndex = idx;
         }
     }
     function getFirstSelectableIndex() {
-        const { groupBy, filteredItems } = context.getState();
-        if (!groupBy || filteredItems.length === 0)
+        const { filteredItems } = state;
+        if (filteredItems.length === 0)
             return 0;
         if (!isItemSelectableCheck(filteredItems[0])) {
             const firstSelectable = filteredItems.findIndex(isItemSelectableCheck);
@@ -60,34 +63,86 @@ export function useHover(context) {
         }
         return 0;
     }
-    function isItemActive(item, val, itemId) {
-        const { multiple } = context.getState();
-        if (multiple)
-            return;
-        const normalized = !val ? null : typeof val === 'string' ? { value: val, label: val } : val;
-        return areItemsEqual(normalized, item, itemId);
+    function isItemActive(item) {
+        const { multiple, normalizedValue, itemId } = state;
+        if (multiple) {
+            if (!Array.isArray(normalizedValue))
+                return false;
+            // Array entries may still be raw strings; normalize each before comparing
+            return normalizedValue.some((v) => areItemsEqual(normalizeItem(v), item, itemId));
+        }
+        if (Array.isArray(normalizedValue))
+            return false;
+        return areItemsEqual(normalizedValue, item, itemId);
     }
     function isItemSelectable(item) {
         return (item.groupHeader && item.selectable) || isItemSelectableCheck(item);
     }
     function handleHover(i) {
-        const { isScrolling } = context.getState();
-        if (isScrolling)
+        if (state.isScrolling)
             return;
-        context.setHoverItemIndex(i);
+        state.hoverItemIndex = i;
+        // Deliberately NOT commit-intent for Tab: browsers synthesize mouseover
+        // when the list renders under a stationary cursor, so hover alone can
+        // happen with zero user action. Intent comes from real pointer movement
+        // over the open list (the list's mousemove handler in Select.svelte).
     }
+    let scrollEndFallback;
     function handleListScroll() {
-        context.setIsScrolling(true);
+        state.isScrolling = true;
+        // scrollend never fires on some browsers (e.g. Safari < 18.2); without a
+        // fallback a single scroll would wedge isScrolling and kill hover + blur
+        clearTimeout(scrollEndFallback);
+        scrollEndFallback = setTimeout(() => {
+            state.isScrolling = false;
+        }, 150);
     }
     function handleListScrollEnd() {
-        context.setIsScrolling(false);
+        clearTimeout(scrollEndFallback);
+        state.isScrolling = false;
     }
+    // Teardown-only effect (not onDestroy: composables are also created inside
+    // $effect.root in tests, where onDestroy has no component context)
+    $effect(() => {
+        return () => clearTimeout(scrollEndFallback);
+    });
+    // Set value index as hover when list opens
+    $effect(() => {
+        const shouldSnap = !state.multiple && state.listOpen && !!state.value && !!state.filteredItems;
+        untrack(() => {
+            // One-shot: a type-ahead keypress that opened the list has already
+            // parked hover on its match — snapping to the value would clobber
+            // it. Consume the flag on every run so it can never go stale.
+            const suppressed = state.suppressValueHoverSnap;
+            state.suppressValueHoverSnap = false;
+            if (shouldSnap && !suppressed)
+                setValueIndexAsHoverIndex();
+        });
+    });
+    // Keep hover on a selectable item
+    $effect(() => {
+        state.filteredItems;
+        state.value;
+        state.multiple;
+        state.listOpen;
+        untrack(() => {
+            if (state.listOpen && state.filteredItems.length > 0) {
+                if (!isItemSelectableCheck(state.filteredItems[state.hoverItemIndex])) {
+                    checkHoverSelectable();
+                }
+            }
+        });
+    });
+    // Reset hover to the first selectable item on filterText change
+    $effect(() => {
+        if (state.filterText) {
+            untrack(() => {
+                state.hoverItemIndex = getFirstSelectableIndex();
+            });
+        }
+    });
     return {
-        computeNextIndex,
         setHoverIndex,
-        setValueIndexAsHoverIndex,
-        checkHoverSelectable,
-        getFirstSelectableIndex,
         isItemActive,
         isItemSelectable,
         handleHover,

package/dist/use-load-options.svelte.d.ts

@@ -1,4 +1,19 @@
-import type { LoadOptionsContext } from './types';
-export declare function useLoadOptions(context: LoadOptionsContext): {
-    handleLoadOptions: (currentFilterText: string, currentDeps: any[]) => void;
+import type { ItemLike, LoadOptionsActions, SelectItem, SelectState } from './types';
+export interface HandleLoadOptionsOptions {
+    /**
+     * Validate the selection against the loaded items (dependency-driven reloads):
+     * entries missing from a non-empty result are dropped; an empty result is no
+     * evidence and never clears.
+     */
+    validateValue?: boolean;
+    /** Defer the fetch through the debounce action (typing); defaults to the legacy prevFilterText comparison. */
+    debounce?: boolean;
+    /** Clear value/items in the disabled branch; the load effect only passes true on an actual disabled transition. */
+    clearValueOnDisabled?: boolean;
+}
+export declare function useLoadOptions<Item extends ItemLike = SelectItem>(state: SelectState<Item>, actions: LoadOptionsActions): {
+    handleLoadOptions: (currentFilterText: string, options?: HandleLoadOptionsOptions) => void;
+    cancelPendingFilterLoad: () => void;
+    retireValidationForFreshSelection: () => void;
+    invalidateLoads: () => void;
 };

package/dist/use-load-options.svelte.js

@@ -1,68 +1,359 @@
-export function useLoadOptions(context) {
-    function handleLoadOptions(currentFilterText, currentDeps) {
-        const { loadOptions, disabled, multiple, value, itemId, useJustValue, justValue, prevFilterText, debounceWait, listOpen } = context.getState();
+import { untrack } from 'svelte';
+import { DEV } from 'esm-env';
+import { convertStringItemsToObjects, getItemProperty } from './utils';
+export function useLoadOptions(state, actions) {
+    // Monotonic token so responses that resolve after a newer request started are discarded
+    let requestSequence = 0;
+    // Whether the newest armed/in-flight load came from typing; only those may be
+    // cancelled by selection or list close — dependency reloads must still land
+    let latestLoadIsFilterDriven = false;
+    // Token of the newest ARMED load and whether it validates the value. A
+    // dependency reload superseded by a plain filter load must still deliver its
+    // validation verdict (its response is authoritative for the deps change),
+    // while a newer validating load owns the verdict itself, and plain
+    // invalidation (disable, unmount, cancel) must deliver nothing.
+    let armedToken = 0;
+    let armedLoadValidates = false;
+    // Filter text of the newest armed/in-flight load while it is live; cleared
+    // once it settles. Lets the effect tell "shown results are stale for this
+    // text" from "a load for this text is already on its way" — mounting with
+    // an initial filterText opens the list after the mount fetch is armed, and
+    // that open must not fire a duplicate fetch.
+    let liveLoadFilterText = undefined;
+    // Token of the newest validating (dependency-driven) load while it is
+    // unsettled; 0 otherwise. If a filter load that superseded it is cancelled,
+    // the deps reload is the most relevant request again and must get its full
+    // authority back — see restoredToken.
+    let liveValidatingToken = 0;
+    // A load allowed to land in full despite no longer being the newest request:
+    // cancelPendingFilterLoad hands currency back to the in-flight deps reload
+    // the cancelled load superseded. Without this, closing the list during a
+    // deps reload discarded both the reload's items and its validation verdict,
+    // leaving stale options and an unvalidated stale selection (the reopen-stale
+    // heuristic could re-fetch the items later, but never the verdict).
+    let restoredToken = 0;
+    // Token of the newest load whose response fully landed (items written).
+    // Lets a user selection tell whether the options it was picked from are
+    // fresher than a still-pending validating reload — see
+    // retireValidationForFreshSelection.
+    let lastLandedToken = 0;
+    // The filter text the currently-displayed items reflect (set when a load
+    // settles). Lets a reopen tell "results are stale for the current text" from
+    // "results already match", so only the former re-fetches.
+    let loadedFilterText = undefined;
+    // Invalidate every pending and in-flight load: a pending one never fetches,
+    // an in-flight response is discarded. Does not touch reactive state, so it
+    // is safe to call during component teardown.
+    function invalidateLoads() {
+        requestSequence++;
+        latestLoadIsFilterDriven = false;
+        restoredToken = 0;
+        liveValidatingToken = 0;
+    }
+    // A filter-driven load becomes moot when the user selects an item, empties
+    // the filter text, or closes the list before the debounce fires.
+    function cancelPendingFilterLoad() {
+        if (!latestLoadIsFilterDriven)
+            return;
+        const validating = liveValidatingToken;
+        invalidateLoads();
+        if (validating !== 0) {
+            // The cancelled filter load had superseded an in-flight dependency
+            // reload. That reload is authoritative for the deps change — items
+            // and validation verdict — so restore its currency and keep the
+            // loading flag up until it settles. It stays restore-eligible so
+            // further type→cancel cycles before it settles hand back to it too;
+            // only a settle, a disable, or unmount (invalidateLoads callers)
+            // ends its authority.
+            restoredToken = validating;
+            liveValidatingToken = validating;
+        }
+        else if (state.loading) {
+            state.loading = false;
+        }
+    }
+    // A user selection picked from results FRESHER than a still-pending
+    // validating (dependency-driven) reload retires that reload's authority:
+    // its late verdict would judge the new selection against results fetched
+    // for the pre-selection filter text and wipe a choice the user made from
+    // post-deps-change options. A selection made from results OLDER than the
+    // reload (a stale pick while it is still in flight) keeps the verdict —
+    // validating exactly that pick is the reload's job.
+    function retireValidationForFreshSelection() {
+        if (liveValidatingToken === 0 || lastLandedToken < liveValidatingToken)
+            return;
+        // The retired reload may also own the restore channel (a cancel handed
+        // currency back to it); spend that too so its items cannot land either
+        if (restoredToken === liveValidatingToken)
+            restoredToken = 0;
+        liveValidatingToken = 0;
+    }
+    function handleLoadOptions(currentFilterText, options = {}) {
+        const { loadOptions, disabled, prevFilterText, debounceWait } = state;
+        const { validateValue = false, debounce: shouldDebounce = currentFilterText !== prevFilterText, clearValueOnDisabled = true, } = options;
         if (loadOptions && !disabled) {
-            context.setLoading(true);
-            const isFilterTextChange = currentFilterText !== prevFilterText;
+            state.loading = true;
+            const token = ++requestSequence;
+            armedToken = token;
+            armedLoadValidates = validateValue;
+            latestLoadIsFilterDriven = shouldDebounce;
+            liveLoadFilterText = currentFilterText;
+            // A new request supersedes any restored one; a newer validating
+            // load also takes over the restore channel from an older one.
+            restoredToken = 0;
+            if (validateValue)
+                liveValidatingToken = token;
+            // Only a dependency-driven reload invalidates the selection: when a
+            // parent select changes, a stale child value must clear. A
+            // filter-driven load merely narrows the results and must not wipe
+            // a selection that happens to fall outside them.
+            const validateValueAgainstLoaded = (loaded) => {
+                // Re-read state after the async boundary
+                const { value, multiple, itemId, useJustValue } = state;
+                if (!value)
+                    return;
+                // An empty (or null) result is no evidence about validity: the
+                // reload queries with the retained filter text (usually '' after
+                // a selection), and a search endpoint returns nothing for an
+                // empty query regardless of the selection. Only a non-empty
+                // result can prove an entry stale, so only it may clear.
+                if (!loaded || loaded.length === 0)
+                    return;
+                const idOf = (entry) => typeof entry === 'string' ? entry : getItemProperty(entry, itemId);
+                const existsInLoaded = (v) => loaded.some((item) => idOf(item) === idOf(v));
+                // One empty representation, matching every other clear path (the
+                // clear button, the last tag removed, a multi->single transition):
+                // `undefined` in both modes, never `null` or `[]`.
+                const clearInvalidatedValue = () => {
+                    state.value = undefined;
+                    if (useJustValue)
+                        state.justValue = undefined;
+                };
+                if (multiple && Array.isArray(value)) {
+                    // Drop only provably stale entries; entries the reload still
+                    // offers survive (justValue re-derives from the value write)
+                    const survivors = value.filter(existsInLoaded);
+                    if (survivors.length === 0) {
+                        clearInvalidatedValue();
+                    }
+                    else if (survivors.length !== value.length) {
+                        state.value = survivors;
+                    }
+                }
+                else if (!existsInLoaded(value)) {
+                    clearInvalidatedValue();
+                }
+            };
             const executeLoad = async () => {
+                // Cancelled or superseded while waiting in the debounce queue: never fetch
+                if (token !== requestSequence)
+                    return;
+                // Re-read the loader at fire time: the prop can be swapped (or
+                // removed) during the debounce wait, and the closure captured at
+                // arm time would run the old fetcher and attribute its response
+                // to the new prop
+                const load = state.loadOptions;
+                if (!load) {
+                    liveLoadFilterText = undefined;
+                    state.loading = false;
+                    return;
+                }
                 try {
-                    const result = await loadOptions(currentFilterText);
+                    const result = await load(currentFilterText);
+                    // Captured before clearing: a reload retired by a fresh user
+                    // selection (retireValidationForFreshSelection) is no longer
+                    // live-validating and must not deliver its verdict below
+                    const wasLiveValidating = token === liveValidatingToken;
+                    if (wasLiveValidating)
+                        liveValidatingToken = 0;
+                    if (token !== requestSequence && token !== restoredToken) {
+                        // Superseded by a newer request: the response must not land, but a
+                        // dependency reload's validation verdict still applies to the deps
+                        // change — unless a newer armed load validates on its own, or a
+                        // fresh user selection retired the verdict.
+                        if (validateValue &&
+                            wasLiveValidating &&
+                            armedToken === requestSequence &&
+                            !armedLoadValidates) {
+                            validateValueAgainstLoaded(result ?? null);
+                        }
+                        return;
+                    }
+                    // A restored load has settled; the channel is spent
+                    if (token === restoredToken)
+                        restoredToken = 0;
                     if (result && result.length > 0 && typeof result[0] === 'string') {
-                        context.setItems(context.convertStringItemsToObjects(result));
+                        state.items = convertStringItemsToObjects(result);
                     }
                     else {
-                        context.setItems(result ? result.slice() : null);
+                        state.items = result ? result.slice() : null;
                     }
-                    // Re-read state after async operation
-                    const state = context.getState();
-                    if (state.value && state.items && state.items.length > 0) {
-                        const items = state.items;
-                        const valueExists = state.multiple
-                            ? Array.isArray(state.value) && state.value.every((v) => items.some((item) => (typeof item === 'string' ? item : item[state.itemId]) === (typeof v === 'string' ? v : v[state.itemId])))
-                            : items.some((item) => (typeof item === 'string' ? item : item[state.itemId]) === (typeof state.value === 'string' ? state.value : state.value[state.itemId]));
-                        if (!valueExists) {
-                            context.setValue(state.multiple ? [] : undefined);
-                            if (state.useJustValue) {
-                                context.setJustValue(state.multiple ? [] : '');
-                            }
-                        }
-                    }
-                    else if (state.value && (!state.items || state.items.length === 0)) {
-                        context.setValue(state.multiple ? [] : undefined);
-                    }
-                    context.setLoading(false);
-                    const finalState = context.getState();
-                    context.onloaded((finalState.items || []));
+                    // Displayed items now reflect this filter text — a reopen with
+                    // the same text won't refetch
+                    loadedFilterText = currentFilterText;
+                    liveLoadFilterText = undefined;
+                    lastLandedToken = token;
+                    if (validateValue)
+                        validateValueAgainstLoaded(state.items);
+                    state.loading = false;
+                    actions.onloaded(state.items || []);
                 }
                 catch (err) {
+                    // An errored load must lose restore eligibility, or a later
+                    // cancel would restore a request that can never settle
+                    if (token === liveValidatingToken)
+                        liveValidatingToken = 0;
+                    if (token !== requestSequence && token !== restoredToken)
+                        return; // superseded; the newer request manages state
+                    if (token === restoredToken)
+                        restoredToken = 0;
+                    // Settled (with an error), so no longer live — a reopen may retry it
+                    liveLoadFilterText = undefined;
                     console.error('loadOptions error:', err);
-                    context.onerror({ type: 'loadOptions', details: err });
-                    context.setItems(null);
-                    context.setLoading(false);
+                    actions.onerror({ type: 'loadOptions', details: err });
+                    state.items = null;
+                    // Deliberately leave loadedFilterText unchanged: an errored load
+                    // did not produce results for this text, so a reopen should
+                    // retry it (a transient failure then recovers). No loop risk —
+                    // a reopen is a manual gesture, so it retries at most once each.
+                    state.loading = false;
                 }
             };
-            if (isFilterTextChange) {
-                context.debounce(executeLoad, debounceWait);
+            if (shouldDebounce) {
+                actions.debounce(executeLoad, debounceWait);
             }
             else {
                 executeLoad();
             }
-            if (currentFilterText.length > 0 && !listOpen) {
-                context.setListOpen(true);
-            }
         }
         else if (loadOptions && disabled) {
-            const state = context.getState();
-            if (state.value || (state.useJustValue && state.justValue)) {
-                context.setValue(state.multiple ? [] : undefined);
-                if (state.useJustValue) {
-                    context.setJustValue(state.multiple ? [] : '');
+            // A response arriving after the disable must not repopulate the control
+            invalidateLoads();
+            if (state.loading)
+                state.loading = false;
+            if (clearValueOnDisabled) {
+                if (state.value || (state.useJustValue && state.justValue)) {
+                    // `undefined` in both modes — see clearInvalidatedValue above
+                    state.value = undefined;
+                    if (state.useJustValue) {
+                        state.justValue = undefined;
+                    }
                 }
+                state.items = null;
             }
-            context.setItems(null);
         }
     }
+    // Snapshot of the previous effect run so it can tell WHICH input changed
+    let prevRun;
+    // Dev-only, once per instance: deps elements are compared by identity, so an
+    // inline object/array literal recreated per parent render re-fires the reload
+    // (and its value validation) on every render.
+    let warnedAboutDepsIdentity = false;
+    function warnIfDepsChangedByIdentityOnly(deps, prevDeps) {
+        if (warnedAboutDepsIdentity)
+            return;
+        try {
+            if (JSON.stringify(deps) !== JSON.stringify(prevDeps))
+                return;
+        }
+        catch {
+            return; // non-serializable deps: skip the heuristic
+        }
+        warnedAboutDepsIdentity = true;
+        console.warn('[svelte-select] loadOptionsDeps changed by identity but not by content. Deps elements ' +
+            'are compared with ===, so an object or array literal created inline re-triggers the ' +
+            'reload — and its selection validation — on every parent render. Pass primitives ' +
+            '(e.g. the id itself) or stable references instead.');
+    }
+    // Run loadOptions when its inputs change: typing non-empty filter text
+    // re-queries (debounced), a loadOptionsDeps change re-queries and re-validates
+    // the value, and toggling disabled clears or reloads the loaded state; mount,
+    // deps, and disabled loads fire immediately. listOpen only matters for the
+    // reopen-stale case below — opening or closing the list otherwise never fetches,
+    // and clearing the filter text on close must not fire a loadOptions('').
+    $effect(() => {
+        const filterText = state.filterText;
+        const deps = [...state.loadOptionsDeps];
+        const disabled = state.disabled;
+        const listOpen = state.listOpen;
+        if (!state.loadOptions) {
+            // Only a genuine removal (a loader ran before) does anything here:
+            // a Select that never had a loader owns its `loading` prop and must
+            // not have it stomped. A removed loader resets the run history —
+            // restoring it later must behave like mount (initial fetch), not
+            // like "nothing changed" — and invalidates: an in-flight response
+            // must not land items (and fire onloaded) on a Select that no
+            // longer has a loader. With no landing left to clear it, the
+            // loading flag drops here too.
+            if (prevRun !== undefined) {
+                prevRun = undefined;
+                untrack(() => {
+                    invalidateLoads();
+                    if (state.loading)
+                        state.loading = false;
+                });
+            }
+            return;
+        }
+        const prev = prevRun;
+        prevRun = { filterText, deps, disabled, listOpen };
+        const isFirstRun = prev === undefined;
+        const depsChanged = !isFirstRun && (deps.length !== prev.deps.length || deps.some((dep, i) => dep !== prev.deps[i]));
+        if (DEV && depsChanged)
+            warnIfDepsChangedByIdentityOnly(deps, prev.deps);
+        const filterTextChanged = !isFirstRun && filterText !== prev.filterText;
+        const disabledChanged = !isFirstRun && disabled !== prev.disabled;
+        // A genuine closed->open transition (not a typing-open, where filterText
+        // also changed) that reveals results stale for the retained filter text.
+        // An armed or in-flight load for the same text (mount with an initial
+        // filterText opens the list right after the mount fetch) is not stale —
+        // its response is already on the way.
+        const loadIsLiveForText = armedToken === requestSequence && liveLoadFilterText === filterText;
+        // No non-empty requirement on filterText: results narrowed by a typed
+        // query whose text was wiped at close (Escape) are just as stale under
+        // an empty input on reopen — the '' re-fetch restores the baseline set.
+        // A mount load still in flight is covered by loadIsLiveForText.
+        const reopenedStale = !isFirstRun &&
+            listOpen &&
+            !prev.listOpen &&
+            !filterTextChanged &&
+            !disabled &&
+            filterText !== loadedFilterText &&
+            !loadIsLiveForText;
+        if (isFirstRun || depsChanged || disabledChanged || (filterTextChanged && filterText.length > 0)) {
+            untrack(() => handleLoadOptions(filterText, {
+                validateValue: depsChanged,
+                debounce: filterTextChanged && !depsChanged && !disabledChanged,
+                clearValueOnDisabled: disabledChanged,
+            }));
+        }
+        else if (reopenedStale) {
+            // Reopened onto results that do not reflect the current filter text —
+            // retained text whose load was cancelled on close
+            // (clearFilterTextOnBlur=false), or an empty input over query-narrowed
+            // results (Escape wiped the text): refresh immediately. A typing-open
+            // is handled by the branch above (filterText changed → debounced); a
+            // pure reopen whose results already match and the initial mount never
+            // reach here.
+            untrack(() => handleLoadOptions(filterText, { debounce: false }));
+        }
+        else if (filterTextChanged) {
+            // Filter text was emptied: a load armed for the old text is moot now
+            untrack(() => cancelPendingFilterLoad());
+        }
+        else if (!listOpen && prev.listOpen) {
+            // The list closed without a text change — a programmatic
+            // bind:listOpen=false write, which never goes through closeList()'s
+            // synchronous cancel: a load armed by typing must not fire (spinner
+            // + stale items) on a closed list. No-op when nothing filter-driven
+            // is armed.
+            untrack(() => cancelPendingFilterLoad());
+        }
+    });
     return {
         handleLoadOptions,
+        cancelPendingFilterLoad,
+        retireValidationForFreshSelection,
+        invalidateLoads,
     };
 }

package/dist/use-value.svelte.d.ts

@@ -1,14 +1,5 @@
-import type { ValueContext, SelectItem, JustValue } from './types';
-export declare function useValue(context: ValueContext): {
-    setValue: () => void;
-    updateValueDisplay: (items?: SelectItem[] | string[] | null) => void;
-    computeJustValue: () => JustValue | undefined;
-    checkValueForDuplicates: () => boolean;
-    findItem: (selection?: SelectItem) => SelectItem | undefined;
-    findItemByValue: (id: string | number) => SelectItem | undefined;
-    dispatchSelectedItem: () => void;
+import type { ItemLike, SelectItem, SelectState, ValueActions } from './types';
+export declare function useValue<Item extends ItemLike = SelectItem>(state: SelectState<Item>, actions: ValueActions): {
     itemSelected: (selection: SelectItem) => void;
-    setupMulti: () => void;
     handleMultiItemClear: (i: number) => Promise<void>;
-    convertStringItemsToObjects: (_items: string[]) => SelectItem[];
 };