@threadlabs/looma 0.1.22 → 0.1.23

package/dist/collection/components/ui-combobox/ui-combobox.js

@@ -0,0 +1,973 @@
+import { Host, h } from "@stencil/core";
+import { createAnchoredSurface } from "../../overlay/positioning";
+import { openOverlay, closeOverlay } from "../../overlay/manager";
+import { formatEditingValue, validateField } from "../../field/validation";
+/** A single editable field with contextual suggestions, optional help and field validation. */
+export class UICombobox {
+    host;
+    /** Accessible visible label, associated with the native text input. */
+    label = '';
+    placeholder = '';
+    name = '';
+    /** Controlled canonical value. Undefined selects uncontrolled mode; null means no selection. */
+    value;
+    defaultValue;
+    /** Controlled raw editing text; independent of canonical selection. */
+    query;
+    defaultQuery = '';
+    /** Immutable configuration; replace the object/context when dependencies change. */
+    config = {};
+    disabled = false;
+    readOnly = false;
+    required = false;
+    size = 'md';
+    disclosure = false;
+    clearable = false;
+    /** Optional description shown by the connected question-mark button. */
+    help = '';
+    queryChange;
+    valueChange;
+    freeEntry;
+    createEntry;
+    dependencyInvalidate;
+    validationChange;
+    /** Supplies the current result rows for framework-owned rich slots. */
+    optionsChange;
+    raw = '';
+    display = '';
+    selected = null;
+    expanded = false;
+    rows = [];
+    active = -1;
+    loading = false;
+    helpOpen = false;
+    lookupError = '';
+    validation = { status: 'pristine', touched: false, dirty: false, issues: [] };
+    input;
+    popup;
+    field;
+    surface;
+    lookup;
+    validationRun;
+    lookupTimer;
+    composing = false;
+    initialRaw = '';
+    overlayId = `ui-combobox-${Math.random().toString(36).slice(2)}`;
+    alive = false;
+    fullSet = false;
+    knownOptions = new Map();
+    awaitingLabel = null;
+    proposedChange;
+    formattedRaw;
+    formattedWith;
+    componentWillLoad() {
+        this.selected = this.value !== undefined ? this.value : this.defaultValue ?? null;
+        this.raw = this.query ?? this.defaultQuery;
+        if (this.query === undefined && !this.raw && this.selected !== null) {
+            this.raw = this.config.options?.find(row => row.value === this.selected)?.label ?? this.selected;
+        }
+        if (this.query === undefined && this.selected !== null && this.raw === this.selected)
+            this.awaitingLabel = this.selected;
+        this.display = this.raw;
+        this.initialRaw = this.raw;
+        this.applyServerIssues();
+    }
+    connectedCallback() { this.alive = true; this.setupSurface(); }
+    componentDidLoad() { this.setupSurface(); }
+    componentDidUpdate() {
+        if (this.input && !this.composing && this.input.value !== this.display)
+            this.input.value = this.display;
+        if (this.expanded)
+            this.surface?.refresh();
+    }
+    disconnectedCallback() {
+        this.alive = false;
+        this.close();
+        this.validationRun?.abort();
+        this.surface?.destroy();
+        this.surface = undefined;
+    }
+    setupSurface() {
+        if (!this.surface && this.popup && this.field)
+            this.surface = createAnchoredSurface(this.popup, { anchor: this.field, placement: 'bottom-start' });
+    }
+    syncValue() {
+        if (this.value === undefined)
+            return;
+        this.selected = this.value;
+        if (this.query === undefined) {
+            const proposal = this.proposedChange;
+            const option = this.config.options?.find(row => row.value === this.selected)
+                ?? (this.selected === null ? undefined : this.knownOptions.get(this.selected));
+            const nextRaw = proposal?.value === this.selected ? proposal.query : option?.label ?? this.selected ?? '';
+            if (proposal?.value !== this.selected || nextRaw !== this.raw) {
+                this.raw = nextRaw;
+                this.display = this.raw;
+                this.formattedRaw = undefined;
+            }
+            this.awaitingLabel = !option && this.selected !== null ? this.selected : null;
+        }
+        this.resetValidation();
+    }
+    syncQuery() {
+        if (this.query === undefined || this.query === this.raw)
+            return;
+        // Only a selection proposal's query echo retains an uncontrolled identity.
+        // Other owner text replacements are edits, just like native input.
+        if (this.value === undefined && this.proposedChange?.query !== this.query)
+            this.selected = null;
+        this.awaitingLabel = null;
+        this.formattedRaw = undefined;
+        this.raw = this.query;
+        this.display = this.raw;
+        this.resetValidation();
+        if (this.expanded)
+            this.search('input');
+    }
+    syncDisabled() {
+        if (this.disabled || this.readOnly) {
+            this.close();
+            this.resetValidation();
+        }
+    }
+    syncConfig(next, previous) {
+        this.validationRun?.abort();
+        if (next.provider !== previous?.provider || next.context !== previous?.context)
+            this.knownOptions.clear();
+        if (next.context !== previous?.context) {
+            this.close();
+            const policy = next.invalidation ?? 'retain-query';
+            const value = policy === 'retain' ? this.selected : null;
+            const query = policy === 'clear' ? '' : this.raw;
+            this.commit(value, query, null, 'invalidation', 'programmatic');
+            this.validation = { status: 'pristine', touched: false, dirty: this.raw !== this.initialRaw, issues: [] };
+        }
+        this.applyServerIssues();
+        if (this.expanded)
+            this.search('context');
+    }
+    applyServerIssues() {
+        const issues = this.config.issues ?? [];
+        if (issues.length)
+            this.setValidation({ issues }, this.validation.touched);
+        else
+            this.resetValidation();
+    }
+    resetValidation() {
+        this.validationRun?.abort();
+        this.validation = { status: 'pristine', touched: this.validation.touched, dirty: this.raw !== this.initialRaw, issues: [] };
+        this.validationChange?.emit(this.validation);
+    }
+    cancelLookup() {
+        clearTimeout(this.lookupTimer);
+        this.lookup?.abort();
+        this.lookup = undefined;
+        this.loading = false;
+    }
+    close() {
+        this.expanded = false;
+        this.active = -1;
+        this.cancelLookup();
+        this.surface?.hide();
+        closeOverlay(this.overlayId);
+    }
+    open(reason = 'input') {
+        if (this.disabled || this.readOnly)
+            return;
+        this.expanded = true;
+        if (this.popup && this.field)
+            this.popup.style.minWidth = `${this.field.getBoundingClientRect().width}px`;
+        this.surface?.show();
+        openOverlay({ id: this.overlayId, element: this.popup, relatedElements: [this.host], modal: false,
+            requestClose: () => this.close() });
+        this.search(reason);
+    }
+    search(reason) {
+        this.cancelLookup();
+        this.fullSet = reason === 'disclosure';
+        this.active = -1;
+        this.lookupError = '';
+        const config = this.config;
+        const query = this.fullSet ? '' : this.raw;
+        const controller = new AbortController();
+        this.lookup = controller;
+        const apply = (options) => {
+            if (controller.signal.aborted || !this.alive)
+                return;
+            for (const option of options)
+                this.knownOptions.set(option.value, option);
+            const selectedOption = this.selected === null ? undefined : this.knownOptions.get(this.selected);
+            if (this.query === undefined && this.awaitingLabel === this.selected && selectedOption) {
+                this.raw = selectedOption.label;
+                this.display = this.raw;
+                this.awaitingLabel = null;
+                this.formattedRaw = undefined;
+                this.resetValidation();
+            }
+            const ids = new Set();
+            this.rows = options.filter(option => {
+                if (ids.has(option.id))
+                    return false;
+                ids.add(option.id);
+                return this.fullSet || (config.filter ? config.filter(option, query, config.context)
+                    : config.provider ? true : option.label.toLocaleLowerCase().includes(query.toLocaleLowerCase()));
+            });
+            const groups = new Map();
+            for (const row of this.rows) {
+                const group = row.group ?? '';
+                if (!groups.has(group))
+                    groups.set(group, []);
+                groups.get(group).push(row);
+            }
+            this.rows = [...groups.values()].flat();
+            this.loading = false;
+            this.optionsChange.emit(this.rows);
+        };
+        if (!config.provider) {
+            apply(config.options ?? []);
+            return;
+        }
+        this.rows = [];
+        this.loading = true;
+        this.lookupTimer = setTimeout(async () => {
+            try {
+                apply(await config.provider({ query, context: config.context, signal: controller.signal, reason }));
+            }
+            catch (error) {
+                if (controller.signal.aborted || !this.alive)
+                    return;
+                this.loading = false;
+                this.lookupError = error instanceof Error ? error.message : 'Unable to load suggestions.';
+            }
+        }, reason === 'disclosure' ? 0 : Math.max(0, config.debounce ?? 200));
+    }
+    get canCreate() {
+        return Boolean(this.config.allowCreate && this.raw.trim() && !this.loading && !this.lookupError
+            && !this.rows.some(row => row.label.toLocaleLowerCase() === this.raw.toLocaleLowerCase()));
+    }
+    format(timing) {
+        if ((this.config.formatOn ?? 'blur') !== timing || !this.input)
+            return;
+        // Selection is now in display coordinates; do not map it as raw a second time.
+        if (this.formattedRaw === this.raw && this.formattedWith === this.config.format)
+            return;
+        const result = formatEditingValue(this.raw, {
+            start: this.input.selectionStart ?? this.raw.length, end: this.input.selectionEnd ?? this.raw.length,
+            direction: this.input.selectionDirection ?? 'none',
+        }, this.config.format);
+        this.formattedRaw = this.raw;
+        this.formattedWith = this.config.format;
+        this.display = result.display;
+        if (this.input.value !== result.display) {
+            this.input.value = result.display;
+            this.input.setSelectionRange(result.selection.start, result.selection.end, result.selection.direction);
+        }
+    }
+    onInput = (event) => {
+        // Composition updates remain entirely native until compositionend.
+        if (this.composing || event.isComposing)
+            return;
+        this.awaitingLabel = null;
+        this.formattedRaw = undefined;
+        this.raw = this.input.value;
+        this.display = this.raw;
+        this.resetValidation();
+        this.format('input');
+        this.queryChange.emit({ query: this.raw, display: this.display, trigger: 'keyboard' });
+        if (this.selected !== null)
+            this.commit(null, this.raw, null, 'clear', 'keyboard');
+        this.open();
+        if (this.config.validateOn === 'input')
+            void this.validate();
+        queueMicrotask(() => {
+            if (this.query !== undefined && this.query !== this.raw)
+                this.syncQuery();
+        });
+    };
+    commit(value, query, option, kind, trigger) {
+        this.awaitingLabel = null;
+        const queryChanged = query !== this.raw;
+        if (this.value === undefined)
+            this.selected = value;
+        if (this.query === undefined && queryChanged) {
+            this.raw = query;
+            this.display = query;
+            this.formattedRaw = undefined;
+        }
+        this.resetValidation();
+        const detail = { value, query, option, kind, trigger };
+        const proposal = { value, query };
+        this.proposedChange = proposal;
+        this.valueChange.emit(detail);
+        if (queryChanged)
+            this.queryChange.emit({ query, display: query, trigger });
+        if (kind === 'create')
+            this.createEntry.emit(detail);
+        if (kind === 'free-entry')
+            this.freeEntry.emit(detail);
+        if (kind === 'invalidation')
+            this.dependencyInvalidate.emit(detail);
+        // Settle after all owner notifications (including Vue's queued update).
+        // A retained prop does not fire a Stencil watcher, so rejection must be
+        // reconciled explicitly while the proposal still identifies an edit echo.
+        queueMicrotask(() => {
+            if (this.proposedChange !== proposal)
+                return;
+            if (this.value !== undefined && this.value !== proposal.value)
+                this.syncValue();
+            if (this.query !== undefined && this.query !== proposal.query) {
+                if (this.value === undefined) {
+                    this.selected = null;
+                    this.resetValidation();
+                }
+                this.syncQuery();
+            }
+            this.proposedChange = undefined;
+        });
+    }
+    choose(index, trigger) {
+        const option = this.rows[index];
+        if (option?.disabled)
+            return;
+        if (option)
+            this.commit(option.value, option.label, option, 'selection', trigger);
+        else if (this.canCreate && index === this.rows.length)
+            this.commit(null, this.raw, null, 'create', trigger);
+        else
+            return;
+        this.close();
+        this.input?.focus();
+        if (this.config.validateOn !== 'submit')
+            queueMicrotask(() => void this.validate());
+    }
+    move(key) {
+        const indices = this.rows.flatMap((row, index) => row.disabled ? [] : [index]);
+        if (this.canCreate)
+            indices.push(this.rows.length);
+        if (!indices.length)
+            return;
+        const current = indices.indexOf(this.active);
+        const next = key === 'Home' ? 0 : key === 'End' ? indices.length - 1
+            : key === 'ArrowDown' ? Math.min(current + 1, indices.length - 1)
+                : current < 0 ? indices.length - 1 : Math.max(0, current - 1);
+        this.active = indices[next];
+        requestAnimationFrame(() => this.host.shadowRoot?.getElementById(`option-${this.active}`)?.scrollIntoView({ block: 'nearest' }));
+    }
+    onKeydown = (event) => {
+        if (this.composing || event.isComposing || this.disabled || this.readOnly)
+            return;
+        if (event.key === 'Escape' && this.expanded) {
+            event.preventDefault();
+            event.stopPropagation();
+            this.close();
+            return;
+        }
+        if (event.key === 'Tab') {
+            this.close();
+            return;
+        }
+        if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+            return;
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            event.preventDefault();
+            if (!this.expanded)
+                this.open('disclosure');
+            this.move(event.key);
+        }
+        else if ((event.key === 'Home' || event.key === 'End') && this.expanded && this.active >= 0) {
+            event.preventDefault();
+            this.move(event.key);
+        }
+        else if (event.key === 'Enter' && this.expanded) {
+            if (this.active >= 0) {
+                event.preventDefault();
+                this.choose(this.active, 'keyboard');
+            }
+            else if (this.config.allowFreeText) {
+                event.preventDefault();
+                this.commit(null, this.raw, null, 'free-entry', 'keyboard');
+                this.close();
+            }
+        }
+    };
+    onFocusOut = (event) => {
+        if (event.relatedTarget instanceof Node && this.host.shadowRoot?.contains(event.relatedTarget))
+            return;
+        this.close();
+        this.format('blur');
+        this.validation = { ...this.validation, touched: true };
+        if (this.config.allowFreeText && this.selected === null)
+            this.commit(null, this.raw, null, 'free-entry', 'keyboard');
+        if ((this.config.validateOn ?? 'blur') === 'blur')
+            void this.validate();
+    };
+    setValidation(result, touched = this.validation.touched) {
+        const blocking = result.issues.some(issue => issue.severity !== 'warning');
+        this.validation = { status: blocking ? 'error' : result.issues.length ? 'warning' : 'valid',
+            touched, dirty: this.raw !== this.initialRaw, ...result };
+        this.validationChange?.emit(this.validation);
+    }
+    /** Validate for submission. Caller submits only non-pending, non-error output. */
+    async validate() {
+        this.validationRun?.abort();
+        const run = new AbortController();
+        this.validationRun = run;
+        this.validation = { ...this.validation, status: 'pending', output: undefined };
+        this.validationChange.emit(this.validation);
+        try {
+            const result = await validateField({ raw: this.raw, value: this.selected, context: this.config.context, signal: run.signal }, this.config);
+            if (this.required && !this.raw.trim())
+                result.issues = [...result.issues, { message: 'A value is required.' }];
+            else if (this.raw && this.selected === null && !this.config.allowFreeText && !this.config.allowCreate)
+                result.issues = [...result.issues, { message: 'Choose a suggestion.' }];
+            if (result.issues.some(issue => issue.severity !== 'warning'))
+                result.output = undefined;
+            if (!run.signal.aborted && this.alive)
+                this.setValidation(result);
+        }
+        catch { /* Aborted work never becomes current field state. */ }
+        return this.validation;
+    }
+    render() {
+        const description = [this.helpOpen ? 'help-text' : '', this.validation.issues.length ? 'validation' : ''].filter(Boolean).join(' ') || undefined;
+        const status = this.loading ? 'Loading suggestions…' : this.lookupError || (this.expanded ? `${this.rows.length} suggestions available.` : '');
+        const groups = [...new Set(this.rows.map(row => row.group ?? ''))];
+        return h(Host, { key: '2378bfd8473852642fef21898f4a756eb3b092ba', "data-size": this.size, "data-validation": this.validation.status, onFocusout: this.onFocusOut }, h("label", { key: '7aba65aeb336d490ddeaf5db9bba9db8ab8b9dbb', htmlFor: "input", part: "label" }, this.label, this.required ? ' *' : ''), h("div", { key: 'ee87156259d0fe1e2e56c4b36667e8daf5e1e2c1', class: "field", part: "field", ref: element => this.field = element }, h("input", { key: '35c5b85ff9a4bcba9bddaf85ff1f118a94aa077b', id: "input", ref: element => this.input = element, role: "combobox", "aria-autocomplete": "list", "aria-expanded": String(this.expanded), "aria-controls": "listbox", "aria-activedescendant": this.expanded && this.active >= 0 ? `option-${this.active}` : undefined, "aria-describedby": description, "aria-invalid": String(this.validation.status === 'error'), "aria-busy": String(this.validation.status === 'pending'), value: this.display, placeholder: this.placeholder, name: this.name || undefined, disabled: this.disabled, readOnly: this.readOnly, required: this.required, autoComplete: "off", part: "input", onInput: this.onInput, onKeyDown: this.onKeydown, onCompositionstart: () => this.composing = true, onCompositionend: () => { this.composing = false; this.onInput(new InputEvent('input')); } }), this.clearable && h("button", { key: '74e4f44836b751ab5e9f794a39b480602e0c106d', type: "button", part: "affordance", "aria-label": `Clear ${this.label}`, disabled: this.disabled || this.readOnly, onClick: () => { this.commit(null, '', null, 'clear', 'pointer'); this.close(); this.input?.focus(); } }, "\u00D7"), this.help && h("button", { key: 'c870ced139fb22baa50a1795ab78f14c38647d34', id: "help", type: "button", part: "affordance", "aria-label": `Help for ${this.label}`, disabled: this.disabled }, h("span", { key: 'ba3dc5128c1941b21b53a5ba78a27017b3df5ec8', "aria-hidden": "true" }, "?")), this.disclosure && h("button", { key: 'eced588e3fa7958dd6185173faaef01219c30243', type: "button", part: "affordance", "aria-label": `Suggestions for ${this.label}`, "aria-controls": "listbox", "aria-expanded": String(this.expanded), disabled: this.disabled || this.readOnly, onClick: () => {
+                if (this.expanded)
+                    this.close();
+                else
+                    this.open('disclosure');
+                this.input?.focus();
+            } }, h("span", { key: '7cb9f7f2bb15246dcdd2348ea0ca656d1d0c8c33', "aria-hidden": "true" }, "\u2304"))), this.help && h("ui-tooltip", { key: 'b1b5d42ca457f9b951758bb5e816c8dbbcd1087d', id: "help-text", for: "help", toggleOnClick: true, onOpen: () => this.helpOpen = true, onClose: () => this.helpOpen = false }, this.help), h("div", { key: '9eca2df66c72917e6bfda21205c2a4ef97dd91d5', class: "popup", part: "popup", hidden: !this.expanded, ref: element => this.popup = element }, h("div", { key: '641e1f137c9cfef5d08ec99f6178e59487a20bf1', id: "listbox", role: "listbox", "aria-label": `${this.label} suggestions`, "aria-busy": String(this.loading) }, groups.map(group => h("div", { role: group ? 'group' : 'presentation', "aria-label": group || undefined }, group && h("div", { class: "group", part: "group" }, group), this.rows.map((row, index) => (row.group ?? '') !== group ? null : h("div", { id: `option-${index}`, role: "option", "aria-selected": String(this.selected === row.value), "aria-disabled": String(Boolean(row.disabled)), "data-active": this.active === index ? '' : undefined, part: "option", class: "option", onPointerDown: event => event.preventDefault(), onClick: () => this.choose(index, 'pointer') }, h("slot", { name: `option-${row.id}` }, h("span", { class: "primary", part: "option-primary" }, row.label), row.description && h("span", { class: "secondary", part: "option-secondary" }, row.description)))))), this.canCreate && h("div", { key: '38a3aa6b2ffae30e6f81e1f89d10c9966dd31b10', id: `option-${this.rows.length}`, role: "option", "aria-selected": "false", class: "option", part: "option", "data-active": this.active === this.rows.length ? '' : undefined, onPointerDown: event => event.preventDefault(), onClick: () => this.choose(this.rows.length, 'pointer') }, h("slot", { key: 'dd3e895ef363f6d30a0c25e4b5092a8feacc63e5', name: "create" }, "Create \u201C", this.raw, "\u201D"))), this.loading ? h("div", { class: "message" }, h("slot", { name: "loading" }, "Loading suggestions\u2026"))
+            : this.lookupError ? h("div", { class: "message" }, h("slot", { name: "error" }, this.lookupError))
+                : !this.rows.length && !this.canCreate ? h("div", { class: "message" }, h("slot", { name: "empty" }, "No suggestions.")) : null), h("div", { key: '9cf12a8fde7d9cfb9e2d2a77669ac4708c7fded6', id: "validation", class: "message", part: "validation", hidden: !this.validation.issues.length }, this.validation.issues.map(issue => h("div", null, issue.message))), h("div", { key: '1c7b1d3f658e500cbf5f5004a76a39511cc79c49', class: "sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" }, status, " ", this.validation.status === 'pending' ? 'Checking value…' : this.validation.issues.map(issue => issue.message).join(' ')));
+    }
+    static get is() { return "ui-combobox"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["ui-combobox.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["ui-combobox.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Accessible visible label, associated with the native text input."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label",
+                "defaultValue": "''"
+            },
+            "placeholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "placeholder",
+                "defaultValue": "''"
+            },
+            "name": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "name",
+                "defaultValue": "''"
+            },
+            "value": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Controlled canonical value. Undefined selects uncontrolled mode; null means no selection."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "value"
+            },
+            "defaultValue": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "default-value"
+            },
+            "query": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Controlled raw editing text; independent of canonical selection."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "query"
+            },
+            "defaultQuery": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "default-query",
+                "defaultValue": "''"
+            },
+            "config": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "ComboboxConfig",
+                    "resolved": "ComboboxConfig",
+                    "references": {
+                        "ComboboxConfig": {
+                            "location": "import",
+                            "path": "../../field/combobox",
+                            "id": "src/field/combobox.ts::ComboboxConfig",
+                            "referenceLocation": "ComboboxConfig"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Immutable configuration; replace the object/context when dependencies change."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "{}"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "readOnly": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "readonly",
+                "defaultValue": "false"
+            },
+            "required": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "required",
+                "defaultValue": "false"
+            },
+            "size": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'sm' | 'md'",
+                    "resolved": "\"md\" | \"sm\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "size",
+                "defaultValue": "'md'"
+            },
+            "disclosure": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disclosure",
+                "defaultValue": "false"
+            },
+            "clearable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "clearable",
+                "defaultValue": "false"
+            },
+            "help": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Optional description shown by the connected question-mark button."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "help",
+                "defaultValue": "''"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "raw": {},
+            "display": {},
+            "selected": {},
+            "expanded": {},
+            "rows": {},
+            "active": {},
+            "loading": {},
+            "helpOpen": {},
+            "lookupError": {},
+            "validation": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "queryChange",
+                "name": "query-change",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "{ query: string; display: string; trigger: 'keyboard' | 'pointer' | 'programmatic' }",
+                    "resolved": "{ query: string; display: string; trigger: \"keyboard\" | \"pointer\" | \"programmatic\"; }",
+                    "references": {}
+                }
+            }, {
+                "method": "valueChange",
+                "name": "value-change",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "ComboboxChange",
+                    "resolved": "ComboboxChange",
+                    "references": {
+                        "ComboboxChange": {
+                            "location": "import",
+                            "path": "../../field/combobox",
+                            "id": "src/field/combobox.ts::ComboboxChange",
+                            "referenceLocation": "ComboboxChange"
+                        }
+                    }
+                }
+            }, {
+                "method": "freeEntry",
+                "name": "free-entry",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "ComboboxChange",
+                    "resolved": "ComboboxChange",
+                    "references": {
+                        "ComboboxChange": {
+                            "location": "import",
+                            "path": "../../field/combobox",
+                            "id": "src/field/combobox.ts::ComboboxChange",
+                            "referenceLocation": "ComboboxChange"
+                        }
+                    }
+                }
+            }, {
+                "method": "createEntry",
+                "name": "create-entry",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "ComboboxChange",
+                    "resolved": "ComboboxChange",
+                    "references": {
+                        "ComboboxChange": {
+                            "location": "import",
+                            "path": "../../field/combobox",
+                            "id": "src/field/combobox.ts::ComboboxChange",
+                            "referenceLocation": "ComboboxChange"
+                        }
+                    }
+                }
+            }, {
+                "method": "dependencyInvalidate",
+                "name": "dependency-invalidate",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "ComboboxChange",
+                    "resolved": "ComboboxChange",
+                    "references": {
+                        "ComboboxChange": {
+                            "location": "import",
+                            "path": "../../field/combobox",
+                            "id": "src/field/combobox.ts::ComboboxChange",
+                            "referenceLocation": "ComboboxChange"
+                        }
+                    }
+                }
+            }, {
+                "method": "validationChange",
+                "name": "validation-change",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "ComboboxValidationState",
+                    "resolved": "ComboboxValidationState",
+                    "references": {
+                        "ComboboxValidationState": {
+                            "location": "import",
+                            "path": "../../field/combobox",
+                            "id": "src/field/combobox.ts::ComboboxValidationState",
+                            "referenceLocation": "ComboboxValidationState"
+                        }
+                    }
+                }
+            }, {
+                "method": "optionsChange",
+                "name": "options-change",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Supplies the current result rows for framework-owned rich slots."
+                },
+                "complexType": {
+                    "original": "readonly ComboboxOption[]",
+                    "resolved": "readonly ComboboxOption<unknown>[]",
+                    "references": {
+                        "ComboboxOption": {
+                            "location": "import",
+                            "path": "../../field/combobox",
+                            "id": "src/field/combobox.ts::ComboboxOption",
+                            "referenceLocation": "ComboboxOption"
+                        }
+                    }
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "validate": {
+                "complexType": {
+                    "signature": "() => Promise<ComboboxValidationState>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        },
+                        "ComboboxValidationState": {
+                            "location": "import",
+                            "path": "../../field/combobox",
+                            "id": "src/field/combobox.ts::ComboboxValidationState",
+                            "referenceLocation": "ComboboxValidationState"
+                        }
+                    },
+                    "return": "Promise<ComboboxValidationState>"
+                },
+                "docs": {
+                    "text": "Validate for submission. Caller submits only non-pending, non-error output.",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "host"; }
+    static get watchers() {
+        return [{
+                "propName": "value",
+                "methodName": "syncValue"
+            }, {
+                "propName": "query",
+                "methodName": "syncQuery"
+            }, {
+                "propName": "disabled",
+                "methodName": "syncDisabled"
+            }, {
+                "propName": "readOnly",
+                "methodName": "syncDisabled"
+            }, {
+                "propName": "config",
+                "methodName": "syncConfig"
+            }];
+    }
+}