@energysage/es-ds-components 6.2.0 → 6.3.1

package/app/components/es-autocomplete-suggestion-text.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import type { EsAutocompleteTextSegment } from '../types';
+import { splitEsAutocompleteText } from '../utils/autocomplete';
+
+interface Props {
+    query?: string;
+    /**
+     * pre-computed segments, e.g. from splitEsAutocompleteTextLines or a search
+     * API's own match offsets. when provided, text/query are ignored.
+     */
+    segments?: EsAutocompleteTextSegment[] | null;
+    text?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+    query: '',
+    segments: null,
+    text: '',
+});
+
+const resolvedSegments = computed(() => props.segments ?? splitEsAutocompleteText(props.text, props.query));
+</script>
+
+<template>
+    <span>
+        <span
+            v-for="(segment, index) in resolvedSegments"
+            :key="index"
+            :class="{ 'font-weight-bold': segment.predictive }"
+            >{{ segment.text }}</span
+        >
+    </span>
+</template>

package/app/components/es-autocomplete.vue

@@ -0,0 +1,224 @@
+<script setup lang="ts">
+import type { EsAutocompleteSuggestion } from '../types';
+
+interface Props {
+    autoSelect?: boolean;
+    autocomplete?: string;
+    clearText?: string;
+    closeText?: string;
+    delay?: number;
+    disabled?: boolean;
+    helpText?: string;
+    label: string;
+    labelSrOnly?: boolean;
+    minChars?: number;
+    noResultsText?: string;
+    placeholder?: string;
+    promptText?: string;
+    required?: boolean;
+    selectOnBlur?: boolean;
+    showOverlayOnFocus?: boolean;
+    state?: boolean | null;
+    suggestionCountText?: (count: number) => string;
+    suggestions: EsAutocompleteSuggestion[];
+    triggerHelpText?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+    autoSelect: false,
+    // keeps browser autofill from competing with our
+    // suggestions list, but can be overridden if necessary
+    autocomplete: 'off',
+    clearText: 'Clear',
+    closeText: 'Close',
+    delay: 300,
+    disabled: false,
+    helpText: 'Type your search and select from dropdown suggestions.',
+    labelSrOnly: false,
+    minChars: 1,
+    noResultsText: 'No results found',
+    placeholder: '',
+    promptText: 'Type for suggestions',
+    required: false,
+    selectOnBlur: false,
+    showOverlayOnFocus: false,
+    state: null,
+    suggestionCountText: (count: number) =>
+        count === 1 ? '1 suggestion available' : `${count} suggestions available`,
+    triggerHelpText: 'Opens a search with suggestions as you type.',
+});
+
+const emit = defineEmits<{
+    blur: [];
+    complete: [query: string];
+    select: [suggestion: EsAutocompleteSuggestion];
+}>();
+
+const model = defineModel<string>({ default: '' });
+
+const slots = useSlots();
+
+const id = useId();
+const errorId = `${id}-error`;
+const helpId = `${id}-help`;
+const triggerHelpId = `${id}-trigger-help`;
+const showError = computed(() => props.state === false && (!!slots.errorMessage || props.required));
+const describedBy = computed(() => (showError.value ? `${helpId} ${errorId}` : helpId));
+// the mobile trigger gets its own hint: it says what activating the field does,
+// while the takeover input's says what to do once it has focus
+const triggerDescribedBy = computed(() => (showError.value ? `${triggerHelpId} ${errorId}` : 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,
+});
+</script>
+
+<template>
+    <div class="es-autocomplete">
+        <div class="es-autocomplete-shell-desktop">
+            <es-autocomplete-desktop
+                :id="id"
+                v-model="model"
+                :auto-select="autoSelect"
+                :autocomplete="autocomplete"
+                :clear-text="clearText"
+                :described-by="describedBy"
+                :disabled="disabled"
+                :label="label"
+                :label-sr-only="labelSrOnly"
+                :no-results-announcement="noResultsAnnouncement"
+                :panel-message="panelMessage"
+                :placeholder="placeholder"
+                :required="required"
+                :select-on-blur="selectOnBlur"
+                :show-overlay-on-focus="showOverlayOnFocus"
+                :state="state"
+                :suggestion-count-text="suggestionCountText"
+                :suggestions="effectiveSuggestions"
+                @blur="emit('blur')"
+                @select="onSelect">
+                <template
+                    v-if="$slots.item"
+                    #item="slotProps">
+                    <slot
+                        name="item"
+                        v-bind="slotProps" />
+                </template>
+            </es-autocomplete-desktop>
+        </div>
+        <div class="es-autocomplete-shell-mobile">
+            <es-autocomplete-mobile
+                :id="id"
+                v-model="model"
+                :auto-select="autoSelect"
+                :autocomplete="autocomplete"
+                :clear-text="clearText"
+                :close-text="closeText"
+                :described-by="describedBy"
+                :disabled="disabled"
+                :label="label"
+                :label-sr-only="labelSrOnly"
+                :no-results-announcement="noResultsAnnouncement"
+                :panel-message="panelMessage"
+                :placeholder="placeholder"
+                :required="required"
+                :select-on-blur="selectOnBlur"
+                :state="state"
+                :suggestion-count-text="suggestionCountText"
+                :suggestions="effectiveSuggestions"
+                :trigger-described-by="triggerDescribedBy"
+                @blur="emit('blur')"
+                @select="onSelect">
+                <template
+                    v-if="$slots.item"
+                    #item="slotProps">
+                    <slot
+                        name="item"
+                        v-bind="slotProps" />
+                </template>
+            </es-autocomplete-mobile>
+        </div>
+        <small
+            v-if="showError"
+            :id="errorId"
+            aria-live="polite"
+            class="text-danger"
+            role="status">
+            <slot
+                v-if="$slots.errorMessage"
+                name="errorMessage" />
+            <template v-else> This field is required. </template>
+        </small>
+        <small
+            v-else-if="$slots.message"
+            class="text-muted">
+            <slot name="message" />
+        </small>
+        <!-- aria-hidden keeps these hints out of a screen reader's reading order —
+             they exist only to be resolved through aria-describedby on focus.
+             kept as separate elements so their IDs can be listed along with the
+             error message ID, when applicable. -->
+        <div
+            :id="helpId"
+            aria-hidden="true"
+            class="sr-only">
+            {{ helpText }}
+        </div>
+        <div
+            :id="triggerHelpId"
+            aria-hidden="true"
+            class="sr-only">
+            {{ triggerHelpText }}
+        </div>
+    </div>
+</template>
+
+<style lang="scss" scoped>
+@use '@energysage/es-ds-styles/scss/mixins/breakpoints' as breakpoints;
+@use '@energysage/es-ds-styles/scss/variables' as variables;
+
+.es-autocomplete {
+    /* match EsFormInput, but allow override by utility classes */
+    margin-bottom: variables.$spacer;
+}
+
+/* ensures that the given rules are applied at XS breakpoint on touch devices.
+ * "hover: none" covers most touch devices except Samsung (which has a bug),
+ * so we also apply them on "pointer: coarse" to catch Samsung devices. */
+@mixin small-touch-screen {
+    @include breakpoints.media-breakpoint-down(sm) {
+        @media (hover: none) {
+            @content;
+        }
+
+        @media (pointer: coarse) {
+            @content;
+        }
+    }
+}
+
+/* show the desktop autocomplete by default */
+.es-autocomplete-shell-mobile {
+    display: none;
+}
+
+/* show the mobile fullscreen takeover experience only on small touch devices */
+@include small-touch-screen {
+    .es-autocomplete-shell-desktop {
+        display: none;
+    }
+
+    .es-autocomplete-shell-mobile {
+        display: block;
+    }
+}
+</style>

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

@@ -0,0 +1,70 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { App } from 'vue';
+import { createApp, nextTick, ref } from 'vue';
+import { useEsAutocompleteAnnouncer } from './autocomplete-announcer';
+
+/** run the composable inside a real component so watchers are scoped */
+function withSetup<T>(composable: () => T): { app: App; result: T } {
+    let result!: T;
+    const app = createApp({
+        setup() {
+            result = composable();
+            return () => null;
+        },
+    });
+    app.mount(document.createElement('div'));
+    return { app, result };
+}
+
+function makeAnnouncer(initial = '') {
+    const source = ref(initial);
+    const { app, result: announced } = withSetup(() => useEsAutocompleteAnnouncer(() => source.value));
+    return { announced, app, source };
+}
+
+describe('useEsAutocompleteAnnouncer', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    it('holds the text back until the listbox has stopped changing', async () => {
+        const { announced, source } = makeAnnouncer();
+        source.value = '34 Prospect St';
+        await nextTick();
+        expect(announced.value).toBe('');
+        vi.advanceTimersByTime(250);
+        expect(announced.value).toBe('34 Prospect St');
+    });
+
+    it('speaks only the last of several texts arriving together', async () => {
+        const { announced, source } = makeAnnouncer();
+        source.value = '34 Prospect St';
+        await nextTick();
+        vi.advanceTimersByTime(100);
+        source.value = '355 Cedar Ct';
+        await nextTick();
+        vi.advanceTimersByTime(100);
+        expect(announced.value).toBe('');
+        vi.advanceTimersByTime(150);
+        expect(announced.value).toBe('355 Cedar Ct');
+    });
+
+    it('empties at once, having nothing to wait behind', async () => {
+        const { announced, source } = makeAnnouncer();
+        source.value = '34 Prospect St';
+        await nextTick();
+        vi.advanceTimersByTime(250);
+        source.value = '';
+        await nextTick();
+        expect(announced.value).toBe('');
+    });
+
+    it('drops a text still waiting when the component goes away', async () => {
+        const { announced, app, source } = makeAnnouncer();
+        source.value = '34 Prospect St';
+        await nextTick();
+        app.unmount();
+        vi.advanceTimersByTime(250);
+        expect(announced.value).toBe('');
+    });
+});

package/app/composables/autocomplete-announcer.ts

@@ -0,0 +1,41 @@
+import { onUnmounted, ref, watch } from 'vue';
+
+// long enough that the changes to the autocomplete have already been read out by
+// screen reader, short enough that the announcement we want (e.g. the
+// auto-selected value and/or number of suggestions) is read out immediately afterward
+const ANNOUNCE_DELAY_MS = 250;
+
+/**
+ * holds a live region's text back until the DOM around it has settled. a screen
+ * reader answers an opening listbox with a burst of its own — expanded, the
+ * listbox, how many items it holds — where each announcement cuts off the one
+ * before, and a polite update made in the same breath is cut off with them.
+ * arriving after the burst, the text is spoken instead of swallowed.
+ */
+export function useEsAutocompleteAnnouncer(text: () => string) {
+    const announced = ref('');
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    function cancel() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+
+    watch(text, (next) => {
+        cancel();
+        // emptying a region announces nothing, so it has nothing to wait behind
+        if (!next) {
+            announced.value = '';
+            return;
+        }
+        timer = setTimeout(() => {
+            announced.value = next;
+        }, ANNOUNCE_DELAY_MS);
+    });
+
+    onUnmounted(cancel);
+
+    return announced;
+}

package/app/composables/autocomplete-choreography.ts

@@ -0,0 +1,258 @@
+interface TakeoverParts {
+    field: HTMLElement | null;
+    takeover: HTMLElement | null;
+    /** the resting readonly combobox input, which the flying ghost clones */
+    trigger: HTMLInputElement | null;
+}
+
+interface TakeoverChoreographyOptions {
+    isOpen: () => boolean;
+    parts: () => TakeoverParts;
+    setOpen: (value: boolean) => void;
+}
+
+const TRANSITION_MS = 300;
+
+/**
+ * the takeover's enter/exit choreography: it cross-fades while a "ghost" of the
+ * field flies between the resting field and the one inside it. the ghost is an
+ * inert clone, so the real input keeps the focus iOS needs to show the keyboard.
+ */
+export function useEsAutocompleteChoreography(options: TakeoverChoreographyOptions) {
+    function transitionsDisabled() {
+        return (
+            typeof matchMedia === 'undefined' ||
+            matchMedia('(prefers-reduced-motion: reduce)').matches ||
+            !('animate' in Element.prototype)
+        );
+    }
+
+    function settle(animation: Animation) {
+        return awaitAnimationOrTimeout(animation, TRANSITION_MS);
+    }
+
+    /**
+     * where a field keeps its text: the gaps from its own box to the text region.
+     * measured, never assumed — only the takeover's field has a clear button,
+     * and it reserves that width over its padding.
+     */
+    function textInsets(input: HTMLInputElement, clearButton: HTMLElement | null) {
+        const style = getComputedStyle(input);
+        return {
+            left: Number.parseFloat(style.paddingLeft) || 0,
+            right: (Number.parseFloat(style.paddingRight) || 0) + (clearButton?.offsetWidth ?? 0),
+        };
+    }
+
+    /** one end of a flight: where the field sits, and what it shows there */
+    interface FlightEnd {
+        insets: { left: number; right: number };
+        placeholder: string;
+        rect: DOMRect;
+    }
+
+    function flyGhost(
+        trigger: HTMLInputElement,
+        from: FlightEnd,
+        to: FlightEnd,
+        decorate?: (ghost: HTMLElement, field: HTMLInputElement) => void,
+    ) {
+        // the flying element wraps the cloned field, because the clear button's
+        // clone must render inside the ghost and an <input> cannot have children.
+        // the clone fills the wrapper, so its own border and background fly.
+        const ghost = document.createElement('div');
+        ghost.setAttribute('aria-hidden', 'true');
+        ghost.style.cssText = 'margin: 0; overflow: hidden; pointer-events: none; position: fixed; z-index: 1060;';
+        const field = trigger.cloneNode(true) as HTMLInputElement;
+        field.removeAttribute('id');
+        // an input's value is a property, so cloning attributes does not bring it
+        field.value = trigger.value;
+        // never a tab stop, and never a second field for an assistive technology
+        field.tabIndex = -1;
+        // an empty field shows the placeholder of wherever it is going, not the
+        // one it came from: the takeover's stands in for the label it covers
+        field.placeholder = to.placeholder;
+        // px-100 is !important, and an important declaration outranks an
+        // animation — the animated insets below own the field's padding
+        field.classList.remove('px-100');
+        field.style.cssText = 'height: 100%; width: 100%;';
+        ghost.append(field);
+        document.body.append(ghost);
+
+        const timing = {
+            duration: TRANSITION_MS,
+            easing: 'cubic-bezier(0.2, 0, 0, 1)',
+            fill: 'both',
+        } as const;
+        const flight = ghost.animate(
+            [from, to].map((end) => ({
+                height: `${end.rect.height}px`,
+                left: `${end.rect.left}px`,
+                top: `${end.rect.top}px`,
+                width: `${end.rect.width}px`,
+            })),
+            timing,
+        );
+        // the text region travels with the box, widening or narrowing by the clear
+        // button's width over the same 300ms the clone spends fading, so a value
+        // pinned to its end slides to its landing place instead of stepping
+        field.animate(
+            [from, to].map((end) => ({
+                paddingLeft: `${end.insets.left}px`,
+                paddingRight: `${end.insets.right}px`,
+            })),
+            timing,
+        );
+        decorate?.(ghost, field);
+        return settle(flight).finally(() => ghost.remove());
+    }
+
+    // only an input's scroll offset positions a value too long to fit, and held at
+    // the end — where both real fields leave the caret — one that fits clamps to
+    // zero anyway. the frame loop is because the flight re-clamps scrollLeft.
+    function holdScrolledToEnd(field: HTMLInputElement) {
+        const hold = () => {
+            if (!field.isConnected) {
+                return;
+            }
+            field.scrollLeft = field.scrollWidth;
+            requestAnimationFrame(hold);
+        };
+        hold();
+    }
+
+    // what the endpoints do not share: the clear button, which only the takeover's
+    // field carries. a clone fades in toward the takeover and out toward the
+    // page, over the space the animated insets reserve.
+    function decorateGhost(
+        ghost: HTMLElement,
+        field: HTMLInputElement,
+        clearButton: HTMLElement | null,
+        direction: 'in' | 'out',
+        text?: string,
+    ) {
+        if (text !== undefined) {
+            // a selection's text: the close starts before the model write is
+            // rendered into the cloned trigger, so the ghost takes the final
+            // text explicitly
+            field.value = text;
+        }
+        holdScrolledToEnd(field);
+        if (direction === 'in') {
+            // the takeover shows no validation, so a ghost flying into it must not
+            // either — the cloned trigger's icon would appear for the flight and
+            // vanish on landing. it also frees the insets below: the icon's room is
+            // reserved with !important, which an animation cannot outrank.
+            field.classList.remove('is-invalid');
+        }
+        if (clearButton) {
+            const clone = clearButton.cloneNode(true) as HTMLElement;
+            // pinned inside the field's border, where the real field lays the
+            // button out in its content box. h-100 comes off for the same reason
+            // px-100 does on the field: !important would beat the insets.
+            const fieldStyle = getComputedStyle(field);
+            const borderY = Number.parseFloat(fieldStyle.borderTopWidth) || 0;
+            const borderX = Number.parseFloat(fieldStyle.borderRightWidth) || 0;
+            clone.classList.remove('h-100');
+            clone.style.cssText = `position: absolute; inset: ${borderY}px ${borderX}px ${borderY}px auto;`;
+            ghost.append(clone);
+            clone.animate(direction === 'in' ? [{ opacity: 0 }, { opacity: 1 }] : [{ opacity: 1 }, { opacity: 0 }], {
+                duration: TRANSITION_MS,
+                easing: 'ease',
+                fill: 'both',
+            });
+        }
+    }
+
+    function enterTransition() {
+        if (transitionsDisabled()) {
+            return;
+        }
+        const { field, takeover, trigger } = options.parts();
+        if (!field || !takeover || !trigger) {
+            return;
+        }
+        // hide both real elements while the ghost flies, so it reads as one element
+        // leaving and arriving. opacity, not visibility: the field holds focus, and
+        // hiding a focused element can blur it and lose the iOS keyboard.
+        field.style.opacity = '0';
+        trigger.style.opacity = '0';
+        const clearButton = field.querySelector<HTMLElement>('.es-autocomplete-clear');
+        const landingInput = field.querySelector('input');
+        void settle(
+            takeover.animate([{ opacity: 0 }, { opacity: 1 }], { duration: TRANSITION_MS, easing: 'ease-out' }),
+        );
+        void flyGhost(
+            trigger,
+            {
+                insets: textInsets(trigger, null),
+                placeholder: trigger.placeholder,
+                rect: trigger.getBoundingClientRect(),
+            },
+            {
+                insets: textInsets(landingInput ?? trigger, clearButton),
+                placeholder: landingInput?.placeholder ?? trigger.placeholder,
+                rect: field.getBoundingClientRect(),
+            },
+            (ghost, ghostField) => decorateGhost(ghost, ghostField, clearButton, 'in'),
+        ).then(() => {
+            field.style.opacity = '';
+            // a close begun during the enter flight owns the trigger's visibility
+            if (!exiting) {
+                trigger.style.opacity = '';
+            }
+        });
+    }
+
+    let exiting = false;
+    async function closeTakeover(selectedText?: string) {
+        if (!options.isOpen() || exiting) {
+            return;
+        }
+        if (transitionsDisabled()) {
+            options.setOpen(false);
+            return;
+        }
+        exiting = true;
+        const { field, takeover, trigger } = options.parts();
+        if (!field || !takeover || !trigger) {
+            options.setOpen(false);
+            exiting = false;
+            return;
+        }
+        takeover.style.pointerEvents = 'none';
+        // hide both real elements while the ghost flies back (see enterTransition)
+        trigger.style.opacity = '0';
+        field.style.opacity = '0';
+        const clearButton = field.querySelector<HTMLElement>('.es-autocomplete-clear');
+        const fade = takeover.animate([{ opacity: 1 }, { opacity: 0 }], {
+            duration: TRANSITION_MS,
+            easing: 'ease-in',
+            fill: 'forwards',
+        });
+        const landingInput = field.querySelector('input');
+        await Promise.all([
+            flyGhost(
+                trigger,
+                {
+                    insets: textInsets(landingInput ?? trigger, clearButton),
+                    placeholder: landingInput?.placeholder ?? trigger.placeholder,
+                    rect: field.getBoundingClientRect(),
+                },
+                {
+                    insets: textInsets(trigger, null),
+                    placeholder: trigger.placeholder,
+                    rect: trigger.getBoundingClientRect(),
+                },
+                (ghost, ghostField) => decorateGhost(ghost, ghostField, clearButton, 'out', selectedText),
+            ),
+            settle(fade),
+        ]);
+        trigger.style.opacity = '';
+        field.style.opacity = '';
+        options.setOpen(false);
+        exiting = false;
+    }
+
+    return { closeTakeover, enterTransition };
+}