@energysage/es-ds-components 6.3.1 → 6.3.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [6.3.2](https://github.com/EnergySage/es-ds/compare/es-ds-components-v6.3.1...es-ds-components-v6.3.2) (2026-10-14)
+
+
+### Bug Fixes
+
+* EsAutocomplete auto-select no longer selects from a stale list ([#1796](https://github.com/EnergySage/es-ds/issues/1796)) ([b680b58](https://github.com/EnergySage/es-ds/commit/b680b58d90ddae913c4c7e715f63d412cd0c4b4f))
+
 ## [6.3.1](https://github.com/EnergySage/es-ds/compare/es-ds-components-v6.3.0...es-ds-components-v6.3.1) (2026-10-12)
 
 

package/app/components/es-autocomplete-desktop.vue

@@ -22,6 +22,7 @@ interface Props {
     state?: boolean | null;
     suggestionCountText: (count: number) => string;
     suggestions: EsAutocompleteSuggestion[];
+    suggestionsPending: boolean;
 }
 
 const props = defineProps<Props>();
@@ -140,6 +141,7 @@ const combobox = useEsAutocompleteCombobox({
     model,
     // arrows navigate exactly what is displayed; nothing while the panel is closed
     suggestions: () => (listboxOpen.value ? visibleSuggestions.value : []),
+    suggestionsPending: () => props.suggestionsPending,
 });
 watch(open, combobox.resetHighlight);
 

package/app/components/es-autocomplete-mobile.vue

@@ -31,6 +31,7 @@ interface Props {
     state?: boolean | null;
     suggestionCountText: (count: number) => string;
     suggestions: EsAutocompleteSuggestion[];
+    suggestionsPending: boolean;
     triggerDescribedBy: string;
 }
 
@@ -83,6 +84,7 @@ const combobox = useEsAutocompleteCombobox({
     model,
     // arrows navigate exactly what is displayed
     suggestions: () => (takeoverOpen.value ? visibleSuggestions.value : []),
+    suggestionsPending: () => props.suggestionsPending,
 });
 
 // the takeover's input announces "expanded" exactly when a list exists

package/app/components/es-autocomplete.vue

@@ -70,16 +70,17 @@ const triggerDescribedBy = computed(() => (showError.value ? `${triggerHelpId} $
 
 // the debounced 'complete' contract, minChars gating, and prompt/no-results
 // messaging live in useEsAutocompleteSearch so the contract is unit-testable
-const { effectiveSuggestions, noResultsAnnouncement, onSelect, panelMessage } = useEsAutocompleteSearch({
-    delay: () => props.delay,
-    emitComplete: (query) => emit('complete', query),
-    emitSelect: (suggestion) => emit('select', suggestion),
-    minChars: () => props.minChars,
-    model,
-    noResultsText: () => props.noResultsText,
-    promptText: () => props.promptText,
-    suggestions: () => props.suggestions,
-});
+const { effectiveSuggestions, noResultsAnnouncement, onSelect, panelMessage, suggestionsPending } =
+    useEsAutocompleteSearch({
+        delay: () => props.delay,
+        emitComplete: (query) => emit('complete', query),
+        emitSelect: (suggestion) => emit('select', suggestion),
+        minChars: () => props.minChars,
+        model,
+        noResultsText: () => props.noResultsText,
+        promptText: () => props.promptText,
+        suggestions: () => props.suggestions,
+    });
 </script>
 
 <template>
@@ -104,6 +105,7 @@ const { effectiveSuggestions, noResultsAnnouncement, onSelect, panelMessage } =
                 :state="state"
                 :suggestion-count-text="suggestionCountText"
                 :suggestions="effectiveSuggestions"
+                :suggestions-pending="suggestionsPending"
                 @blur="emit('blur')"
                 @select="onSelect">
                 <template
@@ -135,6 +137,7 @@ const { effectiveSuggestions, noResultsAnnouncement, onSelect, panelMessage } =
                 :state="state"
                 :suggestion-count-text="suggestionCountText"
                 :suggestions="effectiveSuggestions"
+                :suggestions-pending="suggestionsPending"
                 :trigger-described-by="triggerDescribedBy"
                 @blur="emit('blur')"
                 @select="onSelect">

package/app/composables/autocomplete-combobox.test.ts

@@ -26,6 +26,7 @@ function makeCombobox(
     document.body.append(inputEl);
     const model = ref('solar');
     const suggestions = ref(initialSuggestions);
+    const suggestionsPending = ref(false);
     const close = vi.fn();
     const emitSelect = vi.fn();
     const { result: combobox } = withSetup(() =>
@@ -38,9 +39,10 @@ function makeCombobox(
             inputEl: ref(inputEl),
             model,
             suggestions: () => suggestions.value,
+            suggestionsPending: () => suggestionsPending.value,
         }),
     );
-    return { close, combobox, emitSelect, inputEl, model, suggestions };
+    return { close, combobox, emitSelect, inputEl, model, suggestions, suggestionsPending };
 }
 
 function keydown(key: string, init: { isComposing?: boolean } = {}) {
@@ -462,3 +464,60 @@ describe('useEsAutocompleteCombobox automatic selection', () => {
         expect(emitSelect).not.toHaveBeenCalled();
     });
 });
+
+describe('useEsAutocompleteCombobox automatic selection from a list answering an earlier query', () => {
+    const BEACON = [
+        { id: 'c', text: '1 Beacon Street, Cambridge, MA, USA' },
+        { id: 'b', text: '1 Beacon Street, Boston, MA, USA' },
+    ];
+
+    it('takes nothing on Enter or on the way out once the typing has moved past the list', () => {
+        const { close, combobox, emitSelect, model, suggestionsPending } = makeCombobox(BEACON, {
+            autoSelect: true,
+            selectOnBlur: true,
+        });
+        model.value = '02108';
+        suggestionsPending.value = true;
+        expect(combobox.selectedIndex.value).toBe(-1);
+        expect(combobox.autoSelectedText.value).toBe('');
+        expect(combobox.commitAutoSelection()).toBe(false);
+        const event = keydown('Enter');
+        combobox.onKeydown(event);
+        expect(event.defaultPrevented).toBe(false);
+        expect(close).toHaveBeenCalled();
+        expect(emitSelect).not.toHaveBeenCalled();
+        expect(model.value).toBe('02108');
+    });
+
+    it('keeps holding the first suggestion while it still continues the typed text', () => {
+        const { combobox, emitSelect, model, suggestionsPending } = makeCombobox(BEACON, {
+            autoSelect: true,
+            selectOnBlur: true,
+        });
+        model.value = '1 Beacon Street, Ca';
+        suggestionsPending.value = true;
+        // the field shows exactly what leaving it would take
+        expect(combobox.displayValue.value).toBe('1 Beacon Street, Cambridge, MA, USA');
+        expect(combobox.commitAutoSelection()).toBe(true);
+        expect(emitSelect).toHaveBeenCalledWith(BEACON[0]);
+    });
+
+    it('selects again once the app answers the typed query', () => {
+        const { combobox, model, suggestionsPending } = makeCombobox(BEACON, { autoSelect: true });
+        model.value = '1 Beacon St Bos';
+        suggestionsPending.value = true;
+        expect(combobox.selectedIndex.value).toBe(-1);
+        suggestionsPending.value = false;
+        expect(combobox.selectedIndex.value).toBe(0);
+    });
+
+    it('still lets the user choose from the list explicitly', () => {
+        const { combobox, emitSelect, model, suggestionsPending } = makeCombobox(BEACON, { autoSelect: true });
+        model.value = '1 Beacon St Bos';
+        suggestionsPending.value = true;
+        combobox.onKeydown(keydown('ArrowDown'));
+        combobox.onKeydown(keydown('ArrowDown'));
+        combobox.onKeydown(keydown('Enter'));
+        expect(emitSelect).toHaveBeenCalledWith(BEACON[1]);
+    });
+});

package/app/composables/autocomplete-combobox.ts

@@ -29,6 +29,11 @@ interface AutocompleteComboboxOptions {
      * the trim, and empty while closed so keys cannot walk an invisible list
      */
     suggestions: () => EsAutocompleteSuggestion[];
+    /**
+     * whether the list answers an earlier query than the one typed, because the
+     * app has yet to answer the latest edit
+     */
+    suggestionsPending: () => boolean;
 }
 
 /**
@@ -49,12 +54,28 @@ export function useEsAutocompleteCombobox(options: AutocompleteComboboxOptions)
     // split es-dropdown-select makes)
     const keyboardNav = computed(() => highlightSource.value === 'keyboard');
 
-    // the suggestion the field itself follows under automatic selection: the
-    // first, and only arrowing takes the field off it. a pointer passing over the
-    // list highlights what it is over without touching what the field proposes
-    const autoSelectedSuggestion = computed(() =>
-        options.autoSelect() && !keyboardNav.value ? (options.suggestions()[0] ?? null) : null,
-    );
+    // whether the suggestion's text begins with what is typed, so the field can
+    // show it as the typed text with a remainder after it
+    function continuesTyped(suggestion: EsAutocompleteSuggestion) {
+        const typed = options.model.value;
+        return !!typed && suggestion.text.toLowerCase().startsWith(typed.toLowerCase());
+    }
+
+    // automatic selection's choice: the first suggestion. a list answering an
+    // earlier query keeps it only while it continues the typed text, so Enter or
+    // leaving the field never commits a suggestion the user has typed past
+    const heldSuggestion = computed(() => {
+        const first = options.autoSelect() ? options.suggestions()[0] : undefined;
+        if (!first) {
+            return null;
+        }
+        return !options.suggestionsPending() || continuesTyped(first) ? first : null;
+    });
+
+    // the suggestion the field itself follows under automatic selection, until
+    // arrowing takes the field off it. a pointer passing over the list
+    // highlights what it is over without touching what the field proposes
+    const autoSelectedSuggestion = computed(() => (keyboardNav.value ? null : heldSuggestion.value));
     // automatic selection also holds the highlight, until the user takes it
     const autoHighlighted = computed(() => autoSelectedSuggestion.value !== null && highlightIndex.value < 0);
     // where the highlight actually sits: the user's, or automatic selection's
@@ -80,12 +101,10 @@ export function useEsAutocompleteCombobox(options: AutocompleteComboboxOptions)
     const autoCompletion = computed(() => {
         const typed = options.model.value;
         const suggestion = autoSelectedSuggestion.value;
-        if (!completionAllowed.value || !typed || !suggestion || suggestion.text.length <= typed.length) {
+        if (!completionAllowed.value || !suggestion || suggestion.text.length <= typed.length) {
             return null;
         }
-        return suggestion.text.toLowerCase().startsWith(typed.toLowerCase())
-            ? typed + suggestion.text.slice(typed.length)
-            : null;
+        return continuesTyped(suggestion) ? typed + suggestion.text.slice(typed.length) : null;
     });
 
     // what the input displays: the typed query, the highlighted suggestion while
@@ -103,7 +122,7 @@ export function useEsAutocompleteCombobox(options: AutocompleteComboboxOptions)
     // suggestion that does not complete the typed text changes nothing on screen,
     // and an aria-activedescendant change alone is not reliably spoken, so
     // without this a screen reader hears no selection at all
-    const autoSelectedText = computed(() => (options.autoSelect() ? (options.suggestions()[0]?.text ?? '') : ''));
+    const autoSelectedText = computed(() => heldSuggestion.value?.text ?? '');
 
     const listboxId = `${options.idPrefix}-listbox`;
     function optionId(index: number) {

package/app/composables/autocomplete-search.test.ts

@@ -230,6 +230,72 @@ describe('useEsAutocompleteSearch panel message and suggestion gating', () => {
         expect(search.panelMessage.value).toBe('Type for suggestions');
     });
 
+    it('marks the list pending from an edit until the app answers the typed query', async () => {
+        const { search, suggestions, type } = makeSearch();
+        await type('1 Beacon St');
+        expect(search.suggestionsPending.value).toBe(true);
+        vi.advanceTimersByTime(DELAY);
+        suggestions.value = [{ id: 'a', text: '1 Beacon Street, Cambridge, MA, USA' }];
+        await nextTick();
+        expect(search.suggestionsPending.value).toBe(false);
+
+        // typing past the answered query leaves the list on screen, but pending
+        await type('1 Beacon St Melrose');
+        expect(search.effectiveSuggestions.value).toHaveLength(1);
+        expect(search.suggestionsPending.value).toBe(true);
+
+        // whitespace the trimmed query ignores leaves it answered
+        await type('1 Beacon St ');
+        expect(search.suggestionsPending.value).toBe(false);
+    });
+
+    it('keeps a list pending when it answers a search the typing has already moved past', async () => {
+        const { emitComplete, search, suggestions, type } = makeSearch();
+        await type('1 Beacon');
+        vi.advanceTimersByTime(DELAY);
+        // the answer to "1 Beacon" lands while "1 Beacon St" is still debouncing
+        await type('1 Beacon St');
+        suggestions.value = [{ id: 'a', text: '1 Beacon Street, Cambridge, MA, USA' }];
+        await nextTick();
+        expect(search.suggestionsPending.value).toBe(true);
+
+        vi.advanceTimersByTime(DELAY);
+        expect(emitComplete).toHaveBeenLastCalledWith('1 Beacon St');
+        suggestions.value = [{ id: 'b', text: '1 Beacon Street, Boston, MA, USA' }];
+        await nextTick();
+        expect(search.suggestionsPending.value).toBe(false);
+    });
+
+    it('credits an app that answers synchronously inside its complete handler', async () => {
+        const model = ref('');
+        const suggestions = ref<EsAutocompleteSuggestion[]>([]);
+        const search = withSetup(() =>
+            useEsAutocompleteSearch({
+                delay: () => DELAY,
+                emitComplete: (query) => {
+                    suggestions.value = [{ id: query, text: `${query} batteries` }];
+                },
+                emitSelect: () => undefined,
+                minChars: () => 1,
+                model,
+                noResultsText: () => 'No results found',
+                promptText: () => 'Type for suggestions',
+                suggestions: () => suggestions.value,
+            }),
+        ).result;
+        model.value = 'solar';
+        await nextTick();
+        vi.advanceTimersByTime(DELAY);
+        await nextTick();
+        expect(search.suggestionsPending.value).toBe(false);
+    });
+
+    it('is never pending below minChars, where no list shows', async () => {
+        const { search, type } = makeSearch({ minChars: 3 });
+        await type('so');
+        expect(search.suggestionsPending.value).toBe(false);
+    });
+
     it('gates suggestions below minChars with a referentially stable empty list', async () => {
         const { search, suggestions, type } = makeSearch({ minChars: 3 });
         suggestions.value = [{ id: 'a', text: 'solar batteries' }];

package/app/composables/autocomplete-search.ts

@@ -20,8 +20,9 @@ const EMPTY_SUGGESTIONS: EsAutocompleteSuggestion[] = [];
 
 /**
  * the search state behind es-autocomplete.vue: the debounced 'complete' contract,
- * the minChars gate, the staleness of the app's list after a selection, and the
- * empty-state messaging. here so it is unit-testable without a mount.
+ * the minChars gate, the staleness of the app's list after a selection, which
+ * query that list answers, and the empty-state messaging. here so it is
+ * unit-testable without a mount.
  */
 export function useEsAutocompleteSearch(options: AutocompleteSearchOptions) {
     const { model } = options;
@@ -48,9 +49,13 @@ export function useEsAutocompleteSearch(options: AutocompleteSearchOptions) {
             searchTimeout = null;
         }
     }
+    // the query last sent out, recorded before the emit so an app that answers
+    // synchronously inside its handler is credited with answering it
+    let lastCompletedQuery: string | null = null;
     function scheduleComplete(query: string) {
         cancelPendingComplete();
         searchTimeout = setTimeout(() => {
+            lastCompletedQuery = query;
             options.emitComplete(query);
         }, options.delay());
     }
@@ -60,11 +65,16 @@ export function useEsAutocompleteSearch(options: AutocompleteSearchOptions) {
     // whether the app's last update was empty, which tells "search found nothing"
     // (noResultsText) from "nothing has answered yet" (promptText)
     const noResults = ref(false);
+    // the query the app's list answers: the last one sent out when the list
+    // arrived. an app is expected to drop a response to an earlier query that
+    // arrives late, since nothing here can tell it apart
+    const answeredQuery = ref<string | null>(null);
     watch(
         options.suggestions,
         (list) => {
             noResults.value = list.length === 0;
             suggestionsStale.value = false;
+            answeredQuery.value = lastCompletedQuery;
         },
         // depth 1 so apps that mutate the array in place (push/splice) are seen too
         { deep: 1 },
@@ -73,6 +83,11 @@ export function useEsAutocompleteSearch(options: AutocompleteSearchOptions) {
     // what an open panel shows with nothing to render: the no-results message once
     // a search has come back empty, otherwise the prompt
     const queryLongEnough = computed(() => model.value.trim().length >= options.minChars());
+
+    // the typed query has moved past what the list answers, and its own search
+    // is still debouncing or in flight. the list stays on screen meanwhile, but
+    // automatic selection must not commit from it (see useEsAutocompleteCombobox)
+    const suggestionsPending = computed(() => queryLongEnough.value && model.value.trim() !== answeredQuery.value);
     const panelMessage = computed(() => {
         if (effectiveSuggestions.value.length) {
             return '';
@@ -124,5 +139,5 @@ export function useEsAutocompleteSearch(options: AutocompleteSearchOptions) {
         options.emitSelect(suggestion);
     }
 
-    return { effectiveSuggestions, noResultsAnnouncement, onSelect, panelMessage };
+    return { effectiveSuggestions, noResultsAnnouncement, onSelect, panelMessage, suggestionsPending };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@energysage/es-ds-components",
-    "version": "6.3.1",
+    "version": "6.3.2",
     "private": false,
     "type": "module",
     "description": "An EnergySage Vue component library",