@pienter/ui 0.2.0

package/components/form/combobox/Combobox.vue

@@ -0,0 +1,508 @@
+<template>
+    <div ref="fieldRef" class="pui-field" :data-status="computedStatus">
+        <label v-if="label" class="pui-field__label" :for="inputId">{{
+            label
+        }}</label>
+        <input
+            v-bind="$attrs"
+            :id="inputId"
+            ref="inputRef"
+            class="pui-input pui-combobox__input"
+            type="text"
+            role="combobox"
+            :name="name"
+            :value="displayValue"
+            :placeholder="placeholder"
+            :disabled="disabled"
+            :required="required"
+            :autocomplete="autocomplete"
+            :popovertarget="listboxId"
+            :aria-expanded="isOpen ? 'true' : 'false'"
+            :aria-controls="listboxId"
+            :aria-activedescendant="activeOptionDomId || undefined"
+            aria-autocomplete="list"
+            :aria-invalid="hasErrors ? 'true' : undefined"
+            :aria-describedby="describedBy"
+            @input="onInput"
+            @focus="onFocus"
+            @blur="onBlur"
+            @keydown="onKeydown"
+            @click="onClick"
+        />
+        <ul
+            :id="listboxId"
+            ref="listboxRef"
+            class="pui-combobox__listbox"
+            role="listbox"
+            :aria-label="label || placeholder || 'Options'"
+        >
+            <!--
+              ARIA APG combobox/listbox pattern: keyboard interaction is owned
+              by the <input role="combobox"> above via aria-activedescendant
+              (Arrow/Home/End/Enter handled in onKeydown), so the option rows
+              are intentionally NOT focusable (no tabindex) and carry no per-row
+              key handlers. The @click / @mouseenter here are pointer affordances
+              that mirror the already-complete keyboard path. These three rules
+              assume a self-contained interactive element and false-positive on
+              this pattern; the keyboard behaviour they ask for already exists at
+              the combobox level. See W3C WAI-ARIA APG "Combobox".
+            -->
+            <!-- eslint-disable-next-line vuejs-accessibility/click-events-have-key-events, vuejs-accessibility/interactive-supports-focus, vuejs-accessibility/mouse-events-have-key-events -->
+            <li
+                v-for="(opt, idx) in filteredOptions"
+                :id="`${listboxId}-opt-${idx}`"
+                :key="opt.value"
+                class="pui-combobox__option"
+                role="option"
+                :aria-selected="modelValue === opt.value ? 'true' : 'false'"
+                :aria-disabled="opt.disabled ? 'true' : undefined"
+                :data-active="activeIndex === idx ? 'true' : undefined"
+                :data-disabled="opt.disabled ? 'true' : undefined"
+                @mousedown.prevent
+                @click="onOptionClick(opt)"
+                @mouseenter="onOptionMouseEnter(idx)"
+            >
+                {{ opt.label }}
+            </li>
+            <li
+                v-if="filteredOptions.length === 0"
+                class="pui-combobox__empty"
+                role="presentation"
+            >
+                {{ emptyMessage }}
+            </li>
+        </ul>
+        <p v-if="hint" :id="hintId" class="pui-field__hint">{{ hint }}</p>
+        <ul
+            v-if="errors.length"
+            :id="errorsId"
+            class="pui-field__hint"
+            role="alert"
+        >
+            <li v-for="error in errors" :key="error">{{ error }}</li>
+        </ul>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch, onMounted, onBeforeUnmount } from 'vue';
+import {
+    mountPopover,
+    type PopoverControl,
+    type Placement,
+} from '../../../utils/controllers/popover.js';
+import { generateId } from '../../../utils/a11y/id.js';
+
+defineOptions({ inheritAttrs: false });
+
+interface ComboboxOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+
+const props = withDefaults(
+    defineProps<{
+        /**
+         * Optional id for the input element. Auto-generated if omitted.
+         * The listbox id is derived from this so the
+         * `aria-controls` / `popovertarget` association is stable.
+         */
+        id?: string;
+        /**
+         * Optional visible label rendered above the input. The label
+         * sits inside the `.pui-field` scaffold and is associated with
+         * the input via `for=<inputId>`. Omit for label-less variants
+         * where the consumer supplies their own labelling externally.
+         */
+        label?: string;
+        /**
+         * Selected option value (one of `:options[].value`). The input's
+         * displayed text is the matching option's label; an empty
+         * string clears the selection.
+         */
+        modelValue?: string;
+        /**
+         * Form-control name; submitted with the form when the input
+         * carries a real selection.
+         */
+        name?: string;
+        /**
+         * The list of options to display. Each option needs a unique
+         * `value` and a human-readable `label`; the optional `disabled`
+         * flag mutes the option and skips it in keyboard navigation.
+         */
+        options: ComboboxOption[];
+        /**
+         * Placeholder shown when no option is selected. Doubles as the
+         * `aria-label` fallback on the listbox when no `:label` is set.
+         */
+        placeholder?: string;
+        /** Disables the input (and thus the popover). */
+        disabled?: boolean;
+        /** Marks the input as required for form submission. */
+        required?: boolean;
+        /** Native autocomplete value forwarded to the input. */
+        autocomplete?: string;
+        /** Hint text rendered under the input via the `.pui-field__hint`. */
+        hint?: string;
+        /**
+         * Validation errors. Renders as a list under the input with
+         * `role="alert"` and toggles `aria-invalid="true"` plus the
+         * `data-status="error"` styling on `.pui-field`.
+         */
+        errors?: string[];
+        /**
+         * Explicit status override (`'error'` | `'success'`). When omitted
+         * but `errors.length > 0`, status falls back to `'error'`.
+         */
+        status?: 'error' | 'success';
+        /**
+         * Optional custom filter. Default: case-insensitive substring
+         * match on the option label. Receives the option and the
+         * current input string; returns `true` to keep the option.
+         */
+        filter?: (option: ComboboxOption, query: string) => boolean;
+        /**
+         * Empty-state message shown inside the listbox when filtering
+         * yields no matches. Default: "No results".
+         */
+        emptyMessage?: string;
+        /** Initial popover placement; default `'bottom-start'`. */
+        placement?: Placement;
+        /** Pixel offset between input and listbox; default `4`. */
+        offset?: number;
+    }>(),
+    {
+        id: undefined,
+        label: undefined,
+        modelValue: undefined,
+        name: undefined,
+        placeholder: undefined,
+        disabled: false,
+        required: false,
+        autocomplete: undefined,
+        hint: undefined,
+        errors: () => [],
+        status: undefined,
+        filter: undefined,
+        emptyMessage: 'No results',
+        placement: 'bottom-start',
+        offset: 4,
+    },
+);
+
+const emit = defineEmits<{
+    'update:modelValue': [value: string];
+    'open-change': [value: boolean];
+}>();
+
+const inputId = props.id ?? generateId('combobox');
+const listboxId = `${inputId}-listbox`;
+const hintId = `${inputId}-hint`;
+const errorsId = `${inputId}-errors`;
+
+const inputRef = ref<HTMLInputElement | null>(null);
+const listboxRef = ref<HTMLUListElement | null>(null);
+const fieldRef = ref<HTMLElement | null>(null);
+
+const isOpen = ref(false);
+const query = ref('');
+// `null` means "no active option" — used for both the initial
+// open state (no row highlighted until ArrowDown) and after the
+// user types something that filters out the previously-active row.
+const activeIndex = ref<number | null>(null);
+// Tracks whether the user is actively typing (vs. just focusing the
+// input). When typing, `displayValue` returns the raw query so the
+// user sees their own keystrokes; when not typing, it returns the
+// label of the currently-selected option.
+const isTyping = ref(false);
+
+let control: PopoverControl | null = null;
+
+const hasErrors = computed(() => props.errors.length > 0);
+
+const computedStatus = computed(() => {
+    if (props.status) return props.status;
+    if (hasErrors.value) return 'error';
+    return undefined;
+});
+
+const describedBy = computed(() => {
+    const ids: string[] = [];
+    if (props.hint) ids.push(hintId);
+    if (hasErrors.value) ids.push(errorsId);
+    return ids.length > 0 ? ids.join(' ') : undefined;
+});
+
+// The selected option's label is the canonical `displayValue` when
+// the user is not actively typing. While typing, the raw query is
+// shown so the input echoes the user's keystrokes; the selection
+// only "snaps" back into the input on blur or Enter.
+const selectedOption = computed(() =>
+    props.modelValue
+        ? props.options.find((o) => o.value === props.modelValue)
+        : undefined,
+);
+
+const displayValue = computed(() => {
+    if (isTyping.value) return query.value;
+    return selectedOption.value?.label ?? '';
+});
+
+function defaultFilter(option: ComboboxOption, q: string): boolean {
+    if (!q) return true;
+    return option.label.toLowerCase().includes(q.toLowerCase());
+}
+
+const filteredOptions = computed(() => {
+    const fn = props.filter ?? defaultFilter;
+    // While typing, filter against the live query; while idle,
+    // show all options (the listbox is collapsed in that state
+    // anyway for the no-selection case).
+    const q = isTyping.value ? query.value : '';
+    return props.options.filter((opt) => fn(opt, q));
+});
+
+const activeOptionDomId = computed(() => {
+    if (activeIndex.value == null) return null;
+    return `${listboxId}-opt-${activeIndex.value}`;
+});
+
+function open(): void {
+    if (props.disabled) return;
+    if (!control) return;
+    control.show();
+}
+
+function close(): void {
+    if (!control) return;
+    control.hide();
+}
+
+function moveActive(direction: 1 | -1): void {
+    const len = filteredOptions.value.length;
+    if (len === 0) {
+        activeIndex.value = null;
+        return;
+    }
+    // Skip disabled options on arrow navigation. Loop at most `len`
+    // times so the cursor never falls into an infinite loop on a
+    // listbox that contains only disabled rows.
+    let idx = activeIndex.value;
+    for (let i = 0; i < len; i += 1) {
+        if (idx == null) {
+            idx = direction === 1 ? 0 : len - 1;
+        } else {
+            idx = (idx + direction + len) % len;
+        }
+        if (!filteredOptions.value[idx]?.disabled) {
+            activeIndex.value = idx;
+            scrollActiveIntoView();
+            return;
+        }
+    }
+    // All options disabled — leave activeIndex as it was.
+}
+
+function scrollActiveIntoView(): void {
+    if (activeIndex.value == null || !listboxRef.value) return;
+    const el = listboxRef.value.querySelector<HTMLElement>(
+        `#${CSS.escape(`${listboxId}-opt-${activeIndex.value}`)}`,
+    );
+    el?.scrollIntoView({ block: 'nearest' });
+}
+
+function selectOption(opt: ComboboxOption): void {
+    if (opt.disabled) return;
+    emit('update:modelValue', opt.value);
+    query.value = opt.label;
+    isTyping.value = false;
+    close();
+    // Restore focus to the input so the user can keep tabbing through
+    // the form. The browser doesn't auto-restore focus when the
+    // popover closes via JS show/hide.
+    inputRef.value?.focus();
+}
+
+function onInput(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    query.value = target.value;
+    isTyping.value = true;
+    // First filtered match becomes the active option so Enter has
+    // an obvious target. Skip disabled options.
+    const firstEnabled = filteredOptions.value.findIndex((o) => !o.disabled);
+    activeIndex.value = firstEnabled >= 0 ? firstEnabled : null;
+    if (!isOpen.value) open();
+}
+
+function onFocus(): void {
+    if (props.disabled) return;
+    // Open on focus — the canonical combobox UX is "click into the
+    // field, see the options". Don't reset the query: a refocused
+    // combobox should preserve whatever the user had typed.
+    open();
+}
+
+function onBlur(): void {
+    // Reset typing flag so the displayValue snaps back to the
+    // selected option's label. The popover's light-dismiss handles
+    // closure when focus leaves the surface.
+    isTyping.value = false;
+    query.value = '';
+}
+
+function onClick(): void {
+    // A click on an already-focused input also opens the listbox —
+    // covers the second-click-to-reopen case after the user has
+    // dismissed via Escape and refocused.
+    if (!isOpen.value) open();
+}
+
+function onOptionClick(opt: ComboboxOption): void {
+    selectOption(opt);
+}
+
+function onOptionMouseEnter(idx: number): void {
+    if (filteredOptions.value[idx]?.disabled) return;
+    activeIndex.value = idx;
+}
+
+function onKeydown(event: KeyboardEvent): void {
+    switch (event.key) {
+        case 'ArrowDown':
+            event.preventDefault();
+            if (!isOpen.value) {
+                open();
+                // Defer active-index move until after the popover opens so
+                // the listbox content is visible to scroll into view.
+                const firstEnabled = filteredOptions.value.findIndex(
+                    (o) => !o.disabled,
+                );
+                activeIndex.value = firstEnabled >= 0 ? firstEnabled : null;
+            } else {
+                moveActive(1);
+            }
+            break;
+        case 'ArrowUp':
+            event.preventDefault();
+            if (!isOpen.value) {
+                open();
+                const lastEnabled = [...filteredOptions.value]
+                    .map((o, i) => ({ o, i }))
+                    .reverse()
+                    .find(({ o }) => !o.disabled);
+                activeIndex.value = lastEnabled ? lastEnabled.i : null;
+            } else {
+                moveActive(-1);
+            }
+            break;
+        case 'Home':
+            if (!isOpen.value) return;
+            event.preventDefault();
+            {
+                const firstEnabled = filteredOptions.value.findIndex(
+                    (o) => !o.disabled,
+                );
+                if (firstEnabled >= 0) {
+                    activeIndex.value = firstEnabled;
+                    scrollActiveIntoView();
+                }
+            }
+            break;
+        case 'End':
+            if (!isOpen.value) return;
+            event.preventDefault();
+            {
+                let lastEnabled = -1;
+                for (let i = filteredOptions.value.length - 1; i >= 0; i -= 1) {
+                    if (!filteredOptions.value[i]?.disabled) {
+                        lastEnabled = i;
+                        break;
+                    }
+                }
+                if (lastEnabled >= 0) {
+                    activeIndex.value = lastEnabled;
+                    scrollActiveIntoView();
+                }
+            }
+            break;
+        case 'Enter':
+            if (!isOpen.value) return;
+            if (activeIndex.value == null) return;
+            event.preventDefault();
+            {
+                const opt = filteredOptions.value[activeIndex.value];
+                if (opt) selectOption(opt);
+            }
+            break;
+        case 'Escape':
+            // The native Popover API's light-dismiss already handles
+            // Escape, but we explicitly close so the framework's
+            // `isOpen` state flips synchronously and the next keystroke
+            // doesn't see a stale "open" listbox.
+            if (isOpen.value) {
+                event.preventDefault();
+                close();
+                // Reset typing state so the selected option's label
+                // re-appears in the input — Escape is "abandon current
+                // edit, restore previous selection".
+                isTyping.value = false;
+                query.value = '';
+            }
+            break;
+        case 'Tab':
+            // Tab leaves the combobox; let the browser's default
+            // tabbing run and let the popover's light-dismiss close
+            // the listbox. Don't preventDefault — that would trap
+            // focus inside the field.
+            if (isOpen.value) close();
+            break;
+        default:
+            break;
+    }
+}
+
+onMounted(() => {
+    if (!listboxRef.value || !inputRef.value) return;
+    control = mountPopover(listboxRef.value, {
+        // Anchor the listbox to the input itself so positioning
+        // tracks the input's box (the input is the visual reference,
+        // not the wrapper).
+        anchor: inputRef.value,
+        placement: props.placement,
+        offset: props.offset,
+        // `modal: false` → `popover="auto"` so the browser handles
+        // outside-click / focus-out / Escape light-dismiss. The
+        // listbox closes naturally when the user tabs or clicks away.
+        onOpen: () => {
+            isOpen.value = true;
+            emit('open-change', true);
+        },
+        onClose: () => {
+            isOpen.value = false;
+            activeIndex.value = null;
+            emit('open-change', false);
+        },
+    });
+});
+
+// Watch model changes from the consumer and reset typing state so
+// the input mirrors the new selection's label cleanly.
+watch(
+    () => props.modelValue,
+    () => {
+        isTyping.value = false;
+        query.value = '';
+    },
+);
+
+onBeforeUnmount(() => {
+    control?.teardown();
+    control = null;
+});
+</script>
+
+<style>
+@import './combobox.css';
+</style>

package/components/form/combobox/combobox.css

@@ -0,0 +1,110 @@
+@layer components {
+    /* ===== pui-combobox =====
+   *
+   * Combobox is built on top of the form-primitive scaffold (`.pui-field`
+   * with `.pui-field__label` / `.pui-field__hint` / status-driven recolour)
+   * owned by `text-input.css`. The input itself uses the shared
+   * `.pui-input` class so its border, padding, focus ring, and
+   * disabled state match TextInput / Textarea exactly.
+   *
+   * The listbox is a separate element (a `<ul popover="auto">`) the
+   * controller positions via `mountPopover`. CSS resets the
+   * user-agent popover defaults (`margin: 0; border: 0; inset: auto`)
+   * and supplies the surface look — the Popover API places the
+   * element in the top layer; inline `left`/`top` from the controller
+   * drive the actual placement.
+   */
+
+    /* The input is `.pui-input` (form-primitive surface). Add a tiny
+     marker class for any combobox-specific tweaks; today there are
+     none — the input looks like a plain TextInput, which is the
+     correct affordance per the WAI-ARIA combobox pattern. */
+    .pui-combobox__input {
+        /* Hook for future combobox-specific styling (e.g. trailing
+       chevron icon). v1 keeps the input visually identical to
+       a TextInput. */
+    }
+
+    .pui-combobox__listbox {
+        /* Reset native popover defaults — the user-agent centers a
+       popover at the viewport origin via inset/margin/padding
+       defaults that interfere with anchor positioning. */
+        margin: 0;
+        border: 0;
+        inset: auto;
+        list-style: none;
+
+        /* Surface — uses the lightweight surface treatment shared
+       with DropdownMenu (extension-of-input feel rather than
+       standalone content). */
+        background: var(--bg-clr-surface);
+        border: var(--stroke-sm) solid var(--border-clr-base);
+        border-radius: var(--radius-sm);
+        box-shadow: var(--shadow-spark);
+        color: var(--text-clr-base);
+
+        /* Sizing — matches a typical combobox listbox: at least the
+       input's width (the controller anchors it to the input,
+       so it inherits no width naturally), capped to keep long
+       option lists scrollable. */
+        min-width: 12rem;
+        max-height: 16rem;
+        overflow-y: auto;
+        padding: var(--space-3xs);
+
+        /* Position is set by the controller via inline `left`/`top`. */
+        position: fixed;
+
+        display: flex;
+        flex-direction: column;
+        gap: 1px;
+    }
+
+    .pui-combobox__option {
+        /* Reset list-item styles — options are clickable rows, not
+       bulleted entries. */
+        appearance: none;
+        background: transparent;
+        border: 0;
+        text-align: start;
+        width: 100%;
+        padding: var(--space-2xs) var(--space-xs);
+        font: inherit;
+        font-size: var(--step--1);
+        color: var(--text-clr-base);
+        border-radius: var(--radius-xs);
+        cursor: pointer;
+
+        /* Allow icon + label + optional trailing meta inside the
+       option without consumers fighting the layout. v1 only
+       renders the label string, but the flex container keeps
+       the door open. */
+        display: flex;
+        align-items: center;
+        gap: var(--space-2xs);
+    }
+
+    .pui-combobox__option[data-active='true']:not([data-disabled='true']) {
+        background: var(--bg-clr-surface-2);
+    }
+
+    .pui-combobox__option[aria-selected='true'] {
+        /* Selected option gets a subtle accent so users see which
+       option is currently the model value, distinct from the
+       hover/active highlight (which can land on any row). */
+        font-weight: var(--fw-semibold);
+    }
+
+    .pui-combobox__option[data-disabled='true'] {
+        color: var(--text-clr-muted);
+        cursor: not-allowed;
+        opacity: 0.6;
+    }
+
+    .pui-combobox__empty {
+        padding: var(--space-2xs) var(--space-xs);
+        color: var(--text-clr-muted);
+        font-size: var(--step--1);
+        font-style: italic;
+    }
+}