@energysage/es-ds-components 6.1.1 → 6.3.0

package/app/composables/autocomplete-search.ts

@@ -0,0 +1,128 @@
+import type { Ref } from 'vue';
+import { computed, onUnmounted, ref, watch } from 'vue';
+import type { EsAutocompleteSuggestion } from '../types';
+
+interface AutocompleteSearchOptions {
+    delay: () => number;
+    emitComplete: (query: string) => void;
+    emitSelect: (suggestion: EsAutocompleteSuggestion) => void;
+    minChars: () => number;
+    model: Ref<string>;
+    noResultsText: () => string;
+    promptText: () => string;
+    suggestions: () => EsAutocompleteSuggestion[];
+}
+
+// the shared constant keeps effectiveSuggestions referentially stable across
+// keystrokes below minChars, so downstream watchers don't re-fire for an
+// unchanged empty list
+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.
+ */
+export function useEsAutocompleteSearch(options: AutocompleteSearchOptions) {
+    const { model } = options;
+
+    // a selection makes the app's list stale: it matched the typed query, not the
+    // text just filled in, and no 'complete' fires to refresh it. hold it back —
+    // a refocused panel shows promptText — until the app answers the next edit.
+    const suggestionsStale = ref(false);
+
+    // pass an empty list below minChars so no suggestions show for too-short queries
+    const effectiveSuggestions = computed(() => {
+        if (suggestionsStale.value || model.value.trim().length < options.minChars()) {
+            return EMPTY_SUGGESTIONS;
+        }
+        return options.suggestions();
+    });
+
+    // one cancellable handle for the debounced 'complete': every terminal path
+    // (selection, submit, short query, unmount) cancels through the same place
+    let searchTimeout: ReturnType<typeof setTimeout> | null = null;
+    function cancelPendingComplete() {
+        if (searchTimeout) {
+            clearTimeout(searchTimeout);
+            searchTimeout = null;
+        }
+    }
+    function scheduleComplete(query: string) {
+        cancelPendingComplete();
+        searchTimeout = setTimeout(() => {
+            options.emitComplete(query);
+        }, options.delay());
+    }
+
+    let lastSelectedText: string | null = null;
+
+    // whether the app's last update was empty, which tells "search found nothing"
+    // (noResultsText) from "nothing has answered yet" (promptText)
+    const noResults = ref(false);
+    watch(
+        options.suggestions,
+        (list) => {
+            noResults.value = list.length === 0;
+            suggestionsStale.value = false;
+        },
+        // depth 1 so apps that mutate the array in place (push/splice) are seen too
+        { deep: 1 },
+    );
+
+    // 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());
+    const panelMessage = computed(() => {
+        if (effectiveSuggestions.value.length) {
+            return '';
+        }
+        return noResults.value && queryLongEnough.value ? options.noResultsText() : options.promptText();
+    });
+
+    // rendered into the shells' live regions when nothing is displayed, so screen
+    // readers hear that a search came back empty; each shell announces its own
+    // displayed count. the prompt is guidance, so it is never announced.
+    const noResultsAnnouncement = computed(() =>
+        noResults.value && queryLongEnough.value ? options.noResultsText() : '',
+    );
+
+    watch(model, (newValue) => {
+        cancelPendingComplete();
+        // selecting a suggestion copies its text into the input; that change is
+        // terminal and must not trigger another fetch
+        if (lastSelectedText !== null && newValue === lastSelectedText) {
+            lastSelectedText = null;
+            // after a selection the empty state is the prompt, even for an app
+            // that clears its suggestions in its own select handler
+            noResults.value = false;
+            return;
+        }
+        lastSelectedText = null;
+        // an edit ends the staleness, whatever the app answers with: waiting for
+        // the suggestions prop to change would strand a memoised list that comes
+        // back as the same array, and the panel would never fill again
+        suggestionsStale.value = false;
+        const query = newValue.trim();
+        if (query.length < options.minChars()) {
+            // a fresh (or cleared) query starts from the prompt state, not a stale
+            // "no results" from the previous query
+            noResults.value = false;
+            return;
+        }
+        // the edited query's search is pending: show promptText, not the previous
+        // query's "no results", until the app answers
+        noResults.value = false;
+        scheduleComplete(query);
+    });
+
+    onUnmounted(cancelPendingComplete);
+
+    function onSelect(suggestion: EsAutocompleteSuggestion) {
+        lastSelectedText = suggestion.text;
+        suggestionsStale.value = true;
+        options.emitSelect(suggestion);
+    }
+
+    return { effectiveSuggestions, noResultsAnnouncement, onSelect, panelMessage };
+}

package/app/composables/autocomplete-visible-rows.test.ts

@@ -0,0 +1,209 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from 'vitest';
+import type { App } from 'vue';
+import { createApp, nextTick, ref } from 'vue';
+import type { EsAutocompleteSuggestion } from '../types';
+import { useEsAutocompleteVisibleRows } from './autocomplete-visible-rows';
+
+// NOTE: happy-dom has no real layout, so element geometry (offsetHeight,
+// clientHeight) is mocked per element. These tests cover the counting/limit
+// LOGIC — whole rows per available height, the min-1 floor, and which height
+// constraint wins. Whether real browser layout produces that geometry is
+// covered by the planned Playwright specs (plan §8a).
+
+const apps: App[] = [];
+afterEach(() => {
+    apps.forEach((app) => app.unmount());
+    apps.length = 0;
+    document.body.innerHTML = '';
+});
+
+/** run a composable inside a real component so lifecycle hooks work */
+function withSetup<T>(composable: () => T): T {
+    let result!: T;
+    const app = createApp({
+        setup() {
+            result = composable();
+            return () => null;
+        },
+    });
+    app.mount(document.createElement('div'));
+    apps.push(app);
+    return result;
+}
+
+function suggestionList(count: number): EsAutocompleteSuggestion[] {
+    return Array.from({ length: count }, (_, index) => ({ id: `s${index}`, text: `suggestion ${index}` }));
+}
+
+function makeContainer(
+    rows: { count: number; height: number },
+    size: { clientHeight?: number; maxHeight?: number },
+    extras: { messageOnly?: boolean } = {},
+) {
+    const container = document.createElement('div');
+    // happy-dom only resolves computed styles (the max-height limit) for
+    // elements attached to the document
+    document.body.append(container);
+    if (size.maxHeight !== undefined) {
+        container.style.maxHeight = `${size.maxHeight}px`;
+    }
+    Object.defineProperty(container, 'clientHeight', {
+        configurable: true,
+        get: () => size.clientHeight ?? 0,
+    });
+    if (extras.messageOnly) {
+        container.append(document.createElement('div'));
+        return container;
+    }
+    // rows share one uniform height, matching the es-autocomplete-item styles
+    for (let index = 0; index < rows.count; index += 1) {
+        const el = document.createElement('div');
+        el.dataset.esAutocompleteItem = '';
+        Object.defineProperty(el, 'offsetHeight', { configurable: true, value: rows.height });
+        container.append(el);
+    }
+    return container;
+}
+
+describe('useEsAutocompleteVisibleRows', () => {
+    it('renders the number of whole rows that fit the height limit', async () => {
+        const contentEl = ref<HTMLElement | null>(makeContainer({ count: 7, height: 30 }, { maxHeight: 100 }));
+        const suggestions = ref(suggestionList(7));
+        const fit = withSetup(() => useEsAutocompleteVisibleRows(contentEl, suggestions, 10));
+        await fit.remeasure();
+        // floor(100 / 30) = 3 whole rows; the fourth would be partially shown
+        expect(fit.visibleSuggestions.value).toHaveLength(3);
+        expect(fit.measured.value).toBe(true);
+    });
+
+    it('never trims below one row, even when none fully fits', async () => {
+        const contentEl = ref<HTMLElement | null>(makeContainer({ count: 1, height: 200 }, { maxHeight: 100 }));
+        const suggestions = ref(suggestionList(5));
+        const fit = withSetup(() => useEsAutocompleteVisibleRows(contentEl, suggestions, 10));
+        await fit.remeasure();
+        expect(fit.visibleSuggestions.value).toHaveLength(1);
+    });
+
+    it('a message-only panel (prompt/no-results, no rows) is measured and untrimmed', async () => {
+        const contentEl = ref<HTMLElement | null>(
+            makeContainer({ count: 0, height: 0 }, { maxHeight: 100 }, { messageOnly: true }),
+        );
+        const suggestions = ref<EsAutocompleteSuggestion[]>([]);
+        const fit = withSetup(() => useEsAutocompleteVisibleRows(contentEl, suggestions, 10));
+        await fit.remeasure();
+        expect(fit.measured.value).toBe(true);
+    });
+
+    it('prefers the resolved max-height over the content-sized clientHeight', async () => {
+        // clientHeight is content-limited (40) but max-height allows 100: the count
+        // must come from what COULD fit, or a grown viewport never refills
+        const contentEl = ref<HTMLElement | null>(
+            makeContainer({ count: 5, height: 30 }, { clientHeight: 40, maxHeight: 100 }),
+        );
+        const suggestions = ref(suggestionList(5));
+        const fit = withSetup(() => useEsAutocompleteVisibleRows(contentEl, suggestions, 10));
+        await fit.remeasure();
+        expect(fit.visibleSuggestions.value).toHaveLength(3);
+    });
+
+    it('falls back to clientHeight when there is no max-height (the mobile takeover list)', async () => {
+        const contentEl = ref<HTMLElement | null>(makeContainer({ count: 5, height: 30 }, { clientHeight: 70 }));
+        const suggestions = ref(suggestionList(5));
+        const fit = withSetup(() => useEsAutocompleteVisibleRows(contentEl, suggestions, 10));
+        await fit.remeasure();
+        expect(fit.visibleSuggestions.value).toHaveLength(2);
+    });
+
+    it('re-measures when the suggestions change', async () => {
+        const container = makeContainer({ count: 7, height: 30 }, { maxHeight: 100 });
+        const contentEl = ref<HTMLElement | null>(container);
+        const suggestions = ref(suggestionList(7));
+        const fit = withSetup(() => useEsAutocompleteVisibleRows(contentEl, suggestions, 10));
+        await fit.remeasure();
+        expect(fit.visibleSuggestions.value).toHaveLength(3);
+
+        container.style.maxHeight = '70px';
+        suggestions.value = suggestionList(7);
+        await nextTick(); // the watcher fires
+        await nextTick(); // remeasure's internal tick
+        expect(fit.visibleSuggestions.value).toHaveLength(2);
+    });
+
+    it('adds and removes whole rows on scroll as the available height changes', async () => {
+        const container = makeContainer({ count: 2, height: 30 }, { maxHeight: 70 });
+        const contentEl = ref<HTMLElement | null>(container);
+        const suggestions = ref(suggestionList(7));
+        const fit = withSetup(() => useEsAutocompleteVisibleRows(contentEl, suggestions, 10));
+        await fit.remeasure();
+        expect(fit.visibleSuggestions.value).toHaveLength(2);
+
+        // scrolling moved the anchor and the popper granted more height: the
+        // count grows from the row height alone, without extra rows pre-rendered
+        container.style.maxHeight = '130px';
+        window.dispatchEvent(new Event('scroll'));
+        await new Promise((resolve) => requestAnimationFrame(resolve)); // the handler's deferred frame
+        await nextTick(); // remeasure's internal tick
+        await nextTick();
+        expect(fit.visibleSuggestions.value).toHaveLength(4);
+    });
+
+    it('ignores viewport events while inactive: a closed, still-mounted panel never re-measures on scroll', async () => {
+        const container = makeContainer({ count: 2, height: 30 }, { maxHeight: 70 });
+        const contentEl = ref<HTMLElement | null>(container);
+        const suggestions = ref(suggestionList(7));
+        const active = ref(true);
+        const fit = withSetup(() =>
+            useEsAutocompleteVisibleRows(contentEl, suggestions, 10, { active: () => active.value }),
+        );
+        await fit.remeasure();
+        expect(fit.visibleSuggestions.value).toHaveLength(2);
+
+        active.value = false;
+        container.style.maxHeight = '130px';
+        window.dispatchEvent(new Event('scroll'));
+        await new Promise((resolve) => requestAnimationFrame(resolve));
+        await nextTick();
+        await nextTick();
+        expect(fit.visibleSuggestions.value).toHaveLength(2);
+
+        // reactivating restores the viewport tracking
+        active.value = true;
+        window.dispatchEvent(new Event('scroll'));
+        await new Promise((resolve) => requestAnimationFrame(resolve));
+        await nextTick();
+        await nextTick();
+        expect(fit.visibleSuggestions.value).toHaveLength(4);
+    });
+
+    it('beforeMeasure runs in the same pass, so a limit it writes drives that count', async () => {
+        const container = makeContainer({ count: 7, height: 30 }, {});
+        const contentEl = ref<HTMLElement | null>(container);
+        const suggestions = ref(suggestionList(7));
+        // the caller positions the container and writes its max-height (the
+        // desktop shell's positionPanel) right before each measurement
+        const fit = withSetup(() =>
+            useEsAutocompleteVisibleRows(contentEl, suggestions, 10, {
+                beforeMeasure: () => {
+                    container.style.maxHeight = '70px';
+                },
+            }),
+        );
+        await fit.remeasure();
+        expect(fit.visibleSuggestions.value).toHaveLength(2);
+    });
+
+    it('is unmeasured (list hidden) until a container exists', async () => {
+        const contentEl = ref<HTMLElement | null>(null);
+        const suggestions = ref(suggestionList(3));
+        const fit = withSetup(() => useEsAutocompleteVisibleRows(contentEl, suggestions, 10));
+        expect(fit.measured.value).toBe(false);
+
+        contentEl.value = makeContainer({ count: 3, height: 30 }, { maxHeight: 100 });
+        await nextTick(); // the watcher fires
+        await new Promise((resolve) => requestAnimationFrame(resolve)); // the measure's deferred frame
+        await nextTick(); // remeasure's internal tick
+        expect(fit.measured.value).toBe(true);
+        expect(fit.visibleSuggestions.value).toHaveLength(3);
+    });
+});

package/app/composables/autocomplete-visible-rows.ts

@@ -0,0 +1,116 @@
+import type { Ref } from 'vue';
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import type { EsAutocompleteSuggestion } from '../types';
+
+// Baymard: keep the list manageable — at most this many suggestions, further
+// reduced by the row trim. shared by both shells.
+// https://baymard.com/research-articles/autocomplete-design
+export const ES_AUTOCOMPLETE_MAX_VISIBLE_SUGGESTIONS = 5;
+
+/**
+ * how many suggestion rows fit the space the shell gives them: rows are uniform
+ * height, so the count is the available height over one rendered row's, and
+ * whole rows come and go as that height changes — never a scrollbar or half row.
+ *
+ * the limit comes from the container's max-height or explicit height, re-read on
+ * suggestion changes, resizes and scrolls; anything else calls `remeasure`.
+ * `beforeMeasure` runs first, so a caller positioning the container works from
+ * the same numbers, and `active` gates remeasures while a shell is closed.
+ */
+export function useEsAutocompleteVisibleRows(
+    contentEl: Ref<HTMLElement | null>,
+    suggestions: Ref<EsAutocompleteSuggestion[]>,
+    cap: number,
+    options: { active?: () => boolean; beforeMeasure?: () => void } = {},
+) {
+    const visibleCount = ref(cap);
+    const measured = ref(false);
+
+    function heightLimit(element: HTMLElement): number {
+        const maxHeight = Number.parseFloat(getComputedStyle(element).maxHeight);
+        if (Number.isFinite(maxHeight)) {
+            // max-height is border-box; the rows fit inside the border
+            return maxHeight - Math.max(element.offsetHeight - element.clientHeight, 0);
+        }
+        return element.clientHeight;
+    }
+
+    async function remeasure() {
+        // let any pending render flush so the measured row reflects current content
+        await nextTick();
+        const element = contentEl.value;
+        if (!element) {
+            measured.value = false;
+            return;
+        }
+        options.beforeMeasure?.();
+        // visibleCount never drops below 1, so a row is always rendered to measure
+        // whenever there are suggestions; a message-only panel has none to trim
+        const row = element.querySelector<HTMLElement>('[data-es-autocomplete-item]');
+        if (row) {
+            const fits = Math.floor(heightLimit(element) / row.offsetHeight);
+            visibleCount.value = Math.min(Math.max(fits, 1), cap);
+        } else {
+            visibleCount.value = cap;
+        }
+        measured.value = true;
+    }
+
+    // deferred a frame to coalesce event bursts to one measure per frame
+    let measureFrame: number | null = null;
+    function scheduleRemeasure() {
+        if (measureFrame !== null) {
+            cancelAnimationFrame(measureFrame);
+        }
+        measureFrame = requestAnimationFrame(() => {
+            measureFrame = null;
+            remeasure();
+        });
+    }
+
+    watch(contentEl, (element) => {
+        if (element) {
+            scheduleRemeasure();
+        } else {
+            measured.value = false;
+        }
+    });
+
+    watch(
+        suggestions,
+        () => {
+            if (contentEl.value) {
+                remeasure();
+            }
+        },
+        // depth 1 so apps that mutate the array in place (push/splice) are seen too
+        { deep: 1 },
+    );
+
+    // available height tracks the viewport; re-measure when it changes
+    function onViewportChange() {
+        if (!contentEl.value || options.active?.() === false) {
+            return;
+        }
+        scheduleRemeasure();
+    }
+
+    onMounted(() => {
+        window.addEventListener('resize', onViewportChange);
+        // capture because scroll events do not bubble: this hears scrolls of any
+        // scrollable ancestor, not just the document
+        window.addEventListener('scroll', onViewportChange, { capture: true, passive: true });
+    });
+
+    onBeforeUnmount(() => {
+        window.removeEventListener('resize', onViewportChange);
+        window.removeEventListener('scroll', onViewportChange, { capture: true });
+        if (measureFrame !== null) {
+            cancelAnimationFrame(measureFrame);
+        }
+    });
+
+    const visibleSuggestions = computed(() => suggestions.value.slice(0, visibleCount.value));
+
+    return { measured, remeasure, visibleSuggestions };
+}

package/app/types/es-autocomplete.ts

@@ -0,0 +1,13 @@
+export interface EsAutocompleteTextSegment {
+    /** true when this is text the suggestion would add beyond the typed query — render it bold */
+    predictive: boolean;
+    text: string;
+}
+
+export interface EsAutocompleteSuggestion<T = unknown> {
+    id: string;
+    /** full suggested query, e.g. "backpack rain cover" */
+    text: string;
+    /** opaque app payload, returned untouched on select */
+    value?: T;
+}

package/app/types/index.ts

@@ -1 +1,2 @@
+export type * from './es-autocomplete';
 export type * from './es-carousel';

package/app/utils/animation.ts

@@ -0,0 +1,23 @@
+// how long past an animation's own duration to keep waiting before giving up on
+// it; long enough that a running animation always settles on its own
+const DEADLINE_SLACK_MS = 150;
+
+/**
+ * awaits an animation with a deadline: resolves when it finishes, or cancels it
+ * and resolves shortly after its duration is up. never rejects, so a caller
+ * cannot hang on a hidden tab, whose animation timeline stops advancing.
+ */
+export function awaitAnimationOrTimeout(animation: Animation, durationMs: number) {
+    return new Promise<void>((resolve) => {
+        const timer = setTimeout(() => {
+            animation.cancel();
+            resolve();
+        }, durationMs + DEADLINE_SLACK_MS);
+        animation.finished
+            .catch(() => undefined)
+            .then(() => {
+                clearTimeout(timer);
+                resolve();
+            });
+    });
+}

package/app/utils/autocomplete.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import type { EsAutocompleteTextSegment } from '../types';
+import { splitEsAutocompleteText, splitEsAutocompleteTextLines } from './autocomplete';
+
+// matched (typed) portions render regular; predictive portions render bold
+const regular = (text: string): EsAutocompleteTextSegment => ({ predictive: false, text });
+const bold = (text: string): EsAutocompleteTextSegment => ({ predictive: true, text });
+
+/** segments must always reconstruct the input exactly — no lost or duplicated characters */
+function expectReconstructs(text: string, segments: EsAutocompleteTextSegment[]) {
+    expect(segments.map((segment) => segment.text).join('')).toBe(text);
+}
+
+describe('splitEsAutocompleteText', () => {
+    it('bolds the predictive remainder of a prefix match', () => {
+        expect(splitEsAutocompleteText('solar batteries', 'solar')).toEqual([regular('solar'), bold(' batteries')]);
+    });
+
+    it('matches case-insensitively', () => {
+        expect(splitEsAutocompleteText('Solar Batteries', 'SOLAR')).toEqual([regular('Solar'), bold(' Batteries')]);
+    });
+
+    it('matches tokens in any order, at every word start', () => {
+        expect(splitEsAutocompleteText('123 Main St, Boston, MA', 'boston main')).toEqual([
+            bold('123 '),
+            regular('Main'),
+            bold(' St, '),
+            regular('Boston'),
+            bold(', MA'),
+        ]);
+    });
+
+    it('prefers word starts: "st" matches "St" but not the middle of "Boston"', () => {
+        expect(splitEsAutocompleteText('Boston St', 'st')).toEqual([bold('Boston '), regular('St')]);
+    });
+
+    it('falls back to mid-word matching when a token never matches at a word start', () => {
+        expect(splitEsAutocompleteText('123 Main St', '3')).toEqual([bold('12'), regular('3'), bold(' Main St')]);
+    });
+
+    it('renders everything regular when nothing matches, and for a blank query', () => {
+        expect(splitEsAutocompleteText('solar panels', 'xyz')).toEqual([regular('solar panels')]);
+        expect(splitEsAutocompleteText('solar panels', '  ')).toEqual([regular('solar panels')]);
+    });
+
+    it('merges overlapping token matches', () => {
+        expect(splitEsAutocompleteText('solar panels', 'solar sol')).toEqual([regular('solar'), bold(' panels')]);
+    });
+
+    it('never mis-slices when lowercasing changes string length (e.g. İ)', () => {
+        const text = 'İzmir solar';
+        const segments = splitEsAutocompleteText(text, 'solar');
+        expectReconstructs(text, segments);
+        expect(segments).toContainEqual(regular('solar'));
+    });
+
+    it('always reconstructs the input text exactly', () => {
+        const cases: Array<[string, string]> = [
+            ['solar batteries', 'solar'],
+            ['123 Main St', 'main 123 st'],
+            ['heat pump water heater', 'heat'],
+            ['no match here', 'zzz'],
+            ['', 'anything'],
+        ];
+        for (const [text, query] of cases) {
+            expectReconstructs(text, splitEsAutocompleteText(text, query));
+        }
+    });
+});
+
+describe('splitEsAutocompleteTextLines', () => {
+    const addressLines = ['1200 Beacon St', 'Brookline, MA 02446'];
+
+    it('highlights tokens on the lines they match', () => {
+        expect(splitEsAutocompleteTextLines(['123 Main St', 'Boston, MA 02108'], 'boston main')).toEqual([
+            [bold('123 '), regular('Main'), bold(' St')],
+            [regular('Boston'), bold(', MA 02108')],
+        ]);
+    });
+
+    it('bolds a whole line without its own match when another line matched (bolding mode)', () => {
+        expect(splitEsAutocompleteTextLines(addressLines, 'beacon')).toEqual([
+            [bold('1200 '), regular('Beacon'), bold(' St')],
+            [bold('Brookline, MA 02446')],
+        ]);
+    });
+
+    it('renders every line regular when no line matches', () => {
+        expect(splitEsAutocompleteTextLines(addressLines, 'zzz')).toEqual([
+            [regular('1200 Beacon St')],
+            [regular('Brookline, MA 02446')],
+        ]);
+    });
+
+    it('decides the word-start fallback across all lines together', () => {
+        // "st" has a word-start match on line 1, so it must NOT fall back to
+        // mid-word matching inside "Brookline" on line 2
+        expect(splitEsAutocompleteTextLines(addressLines, 'beacon st')).toEqual([
+            [bold('1200 '), regular('Beacon'), bold(' '), regular('St')],
+            [bold('Brookline, MA 02446')],
+        ]);
+    });
+});