@threadlabs/looma 0.1.28 → 0.2.1

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

@@ -2,16 +2,27 @@ 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. */
+/**
+ * A single editable field with contextual suggestions, optional help and field validation.
+ * With `multiple`, it becomes a multi-value tag field: `value` holds the selected
+ * items, chips render before the cursor, and add/remove/create item events fire.
+ */
 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. */
+    /**
+     * Controlled canonical value. Undefined selects uncontrolled mode; null means no selection.
+     * With `multiple`, this is the controlled list of selected items instead.
+     */
     value;
     defaultValue;
+    /** Render selected values as removable chips before the cursor. `value` becomes the item list. */
+    multiple = false;
+    /** Characters that commit the current query and leave the input ready for the next item (multiple only). */
+    tokenSeparators = [];
     /** Controlled raw editing text; independent of canonical selection. */
     query;
     defaultQuery = '';
@@ -28,6 +39,7 @@ export class UICombobox {
     /** Optional description shown by the connected question-mark button. */
     help = '';
     queryChange;
+    /** Single mode: the ComboboxChange. Multiple mode: the full current item list on any change. */
     valueChange;
     freeEntry;
     createEntry;
@@ -35,6 +47,12 @@ export class UICombobox {
     validationChange;
     /** Supplies the current result rows for framework-owned rich slots. */
     optionsChange;
+    /** Multiple mode: a suggestion or exact-match token was committed as a new item. */
+    addItem;
+    /** Multiple mode: a selected item was removed via chip keyboard controls. */
+    removeItem;
+    /** Multiple mode: an unmatched query was submitted for creation. */
+    createItem;
     raw = '';
     display = '';
     selected = null;
@@ -62,8 +80,21 @@ export class UICombobox {
     proposedChange;
     formattedRaw;
     formattedWith;
+    /** Multiple mode: the controlled selected items (from `value`). Empty otherwise. */
+    get items() {
+        return this.multiple && Array.isArray(this.value) ? this.value : [];
+    }
+    get selectedValues() { return new Set(this.items.map(item => item.value)); }
     componentWillLoad() {
-        this.selected = this.value !== undefined ? this.value : this.defaultValue ?? null;
+        if (this.multiple) {
+            this.selected = null;
+            this.raw = this.query ?? this.defaultQuery;
+            this.display = this.raw;
+            this.initialRaw = this.raw;
+            this.applyServerIssues();
+            return;
+        }
+        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;
@@ -94,7 +125,8 @@ export class UICombobox {
             this.surface = createAnchoredSurface(this.popup, { anchor: this.field, placement: 'bottom-start' });
     }
     syncValue() {
-        if (this.value === undefined)
+        // Multiple mode: `value` is the item list; Stencil re-renders chips on reference change.
+        if (this.multiple || this.value === undefined)
             return;
         this.selected = this.value;
         if (this.query === undefined) {
@@ -139,9 +171,15 @@ export class UICombobox {
         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');
+            if (this.multiple) {
+                if (policy === 'clear')
+                    this.setMultiQuery('', 'programmatic');
+            }
+            else {
+                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();
@@ -207,12 +245,21 @@ export class UICombobox {
                 this.resetValidation();
             }
             const ids = new Set();
+            const selected = this.multiple ? this.selectedValues : undefined;
             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()));
+                if (this.fullSet)
+                    return true;
+                // Multiple mode always hides already-selected items and, absent an owner
+                // filter, falls back to a client label match (there is no unfiltered pass-through).
+                if (selected)
+                    return !selected.has(option.value)
+                        && (config.filter ? config.filter(option, query, config.context)
+                            : option.label.toLocaleLowerCase().includes(query.toLocaleLowerCase()));
+                return 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) {
@@ -332,6 +379,18 @@ export class UICombobox {
         const option = this.rows[index];
         if (option?.disabled)
             return;
+        if (this.multiple) {
+            if (option)
+                this.addSelectedItem(option, trigger);
+            else if (this.canCreate && index === this.rows.length)
+                this.createSelectedItem(this.raw.trim(), trigger);
+            else
+                return;
+            this.setMultiQuery('', trigger);
+            this.close();
+            this.input?.focus();
+            return;
+        }
         if (option)
             this.commit(option.value, option.label, option, 'selection', trigger);
         else if (this.canCreate && index === this.rows.length)
@@ -343,6 +402,105 @@ export class UICombobox {
         if (this.config.validateOn !== 'submit')
             queueMicrotask(() => void this.validate());
     }
+    // --- Multiple-mode helpers ---------------------------------------------
+    emitItems(items) { this.valueChange.emit(items); }
+    setMultiQuery(query, trigger) {
+        if (this.query === undefined) {
+            this.raw = query;
+            this.display = query;
+            this.formattedRaw = undefined;
+        }
+        if (this.input)
+            this.input.value = query;
+        this.queryChange.emit({ query, display: query, trigger });
+    }
+    addSelectedItem(option, trigger) {
+        this.addItem.emit({ item: option, index: this.items.length, trigger });
+        this.emitItems([...this.items, option]);
+    }
+    createSelectedItem(query, trigger) {
+        if (!query)
+            return;
+        this.createItem.emit({ query, trigger });
+    }
+    commitQuery(trigger) {
+        const query = this.raw.trim();
+        if (!query)
+            return;
+        const normalized = query.toLocaleLowerCase();
+        const option = this.rows.find(row => row.label.trim().toLocaleLowerCase() === normalized);
+        if (option) {
+            this.setMultiQuery('', trigger);
+            this.addSelectedItem(option, trigger);
+        }
+        else if (this.config.allowCreate) {
+            this.setMultiQuery('', trigger);
+            this.createSelectedItem(query, trigger);
+        }
+    }
+    removeItemAt(index, trigger) {
+        const item = this.items[index];
+        if (!item || item.disabled || this.disabled || this.readOnly)
+            return;
+        this.removeItem.emit({ item, index, trigger });
+        this.emitItems(this.items.filter((_, position) => position !== index));
+        requestAnimationFrame(() => {
+            const buttons = this.host.shadowRoot?.querySelectorAll('[part="item"]') ?? [];
+            const next = buttons[Math.min(index, buttons.length - 1)] ?? buttons[index - 1];
+            if (next && next.dataset.value !== item.value)
+                next.focus();
+            else
+                void this.focusInput();
+        });
+    }
+    focusItem(index) {
+        this.host.shadowRoot?.querySelectorAll('[part="item"]')[index]?.focus();
+    }
+    onItemKeyDown = (event, index) => {
+        if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+            return;
+        if (event.key === 'ArrowLeft') {
+            event.preventDefault();
+            event.stopPropagation();
+            this.focusItem(Math.max(0, index - 1));
+        }
+        else if (event.key === 'ArrowRight') {
+            event.preventDefault();
+            event.stopPropagation();
+            if (index === this.items.length - 1)
+                void this.focusInput();
+            else
+                this.focusItem(index + 1);
+        }
+        else if (event.key === 'Backspace' || event.key === 'Delete') {
+            event.preventDefault();
+            event.stopPropagation();
+            this.removeItemAt(index, 'keyboard');
+        }
+    };
+    handleMultipleKeydown(event) {
+        if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+            return false;
+        if (this.tokenSeparators.includes(event.key)) {
+            event.preventDefault();
+            event.stopPropagation();
+            this.commitQuery('keyboard');
+            return true;
+        }
+        if (this.raw || (this.input?.selectionStart ?? 0) > 0)
+            return false;
+        if (event.key === 'ArrowLeft' && this.items.length) {
+            event.preventDefault();
+            this.focusItem(this.items.length - 1);
+            return true;
+        }
+        if (event.key === 'Backspace' && this.items.length) {
+            event.preventDefault();
+            this.removeItemAt(this.items.length - 1, 'keyboard');
+            return true;
+        }
+        return false;
+    }
     move(key) {
         const indices = this.rows.flatMap((row, index) => row.disabled ? [] : [index]);
         if (this.canCreate)
@@ -359,6 +517,8 @@ export class UICombobox {
     onKeydown = (event) => {
         if (this.composing || event.isComposing || this.disabled || this.readOnly)
             return;
+        if (this.multiple && this.handleMultipleKeydown(event))
+            return;
         if (event.key === 'Escape' && this.expanded) {
             event.preventDefault();
             event.stopPropagation();
@@ -399,7 +559,7 @@ export class UICombobox {
         this.close();
         this.format('blur');
         this.validation = { ...this.validation, touched: true };
-        if (this.config.allowFreeText && this.selected === null)
+        if (!this.multiple && this.config.allowFreeText && this.selected === null)
             this.commit(null, this.raw, null, 'free-entry', 'keyboard');
         if ((this.config.validateOn ?? 'blur') === 'blur')
             void this.validate();
@@ -437,18 +597,18 @@ export class UICombobox {
         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: '1f00d9a83729d9c2147ced7e5006b928d1b5e51d', "data-size": this.size, "data-validation": this.validation.status, onFocusout: this.onFocusOut }, h("label", { key: '10353b147cc68ef1d67be0988849af1527fcf9ba', htmlFor: "input", part: "label", class: this.labelVisibility === 'sr-only' ? 'sr-only' : undefined }, this.label, this.required ? ' *' : ''), h("div", { key: '74bb53137d9343add37c22f3ac503eccf41807a9', class: "field", part: "field", ref: element => this.field = element, onClick: event => {
+        return h(Host, { key: 'fc4c0192d3be88d8c0199ae1bcca44232bd22351', "data-size": this.size, "data-validation": this.validation.status, onFocusout: this.onFocusOut }, h("label", { key: 'bdd0d244c6ef448978fa77aac3a2d3b71d713553', htmlFor: "input", part: "label", class: this.labelVisibility === 'sr-only' ? 'sr-only' : undefined }, this.label, this.required ? ' *' : ''), h("div", { key: 'afb3972aab52171a3b25ede863c31059e56f5d91', class: "field", part: "field", ref: element => this.field = element, onClick: event => {
                 if (!event.composedPath().some(node => node instanceof HTMLButtonElement))
                     this.input?.focus();
-            } }, h("slot", { key: '24c26916365013faa4a78bd4fe0d01f6c129c703', name: "start" }), h("input", { key: '835d19e66ec4a24c1a83f43bbc256fa2a9e3332f', 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: '326c1e24d3c417c3a72acd8234a53937b388ba79', 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: '6aeb62dc2935eb95670caa1d2028c0931dc362b2', id: "help", type: "button", part: "affordance", "aria-label": `Help for ${this.label}`, disabled: this.disabled }, h("span", { key: '9317be0fbb0c1bbb91061be69f38037a97a4c36b', "aria-hidden": "true" }, "?")), this.disclosure && h("button", { key: '1cd2a0ea92df1144ff2297fcf64df7b3d0f4713a', type: "button", part: "affordance", "aria-label": `Suggestions for ${this.label}`, "aria-controls": "listbox", "aria-expanded": String(this.expanded), disabled: this.disabled || this.readOnly, onClick: () => {
+            } }, h("slot", { key: '65e4e201d6c11cd2638e392e1298662de7ba4d57', name: "start" }), this.multiple && h("div", { key: 'b80b5b85fa0540139b9756fcc494aef9df245c15', class: "items", role: "group", "aria-label": `Selected ${this.label}` }, this.items.map((item, index) => h("button", { type: "button", part: "item", class: "item", "data-value": item.value, tabIndex: -1, disabled: this.disabled || this.readOnly || item.disabled, "aria-label": `${item.label}, press Delete or Backspace to remove`, onKeyDown: event => this.onItemKeyDown(event, index) }, h("slot", { name: `item-${item.id}` }, h("ui-chip", { appearance: "pill" }, item.label))))), h("input", { key: '64f76055ae412cc87119270eec10c69000a72563', 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: 'eac4c18dadcea92065af4ecd871d925ef1248d47', 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: '9a559d49a495ead3dbf159f170c594e0aaa0d0d0', id: "help", type: "button", part: "affordance", "aria-label": `Help for ${this.label}`, disabled: this.disabled }, h("span", { key: '73940e568b976f85399d5baa5e247a4a606d0039', "aria-hidden": "true" }, "?")), this.disclosure && h("button", { key: '30dd6746ffb121888a4c4fb6df54720906badf78', 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: '0188b2d0e8cc7b7ff4d1a2175a0ff0b47d9c7d98', "aria-hidden": "true" }, "\u2304"))), this.help && h("ui-tooltip", { key: 'e09fd35274c3e1fa6e408850d72f7a07c2bb4baf', id: "help-text", for: "help", toggleOnClick: true, onOpen: () => this.helpOpen = true, onClose: () => this.helpOpen = false }, this.help), h("div", { key: 'ddf83a5944dd03fc7eb580b81fcf291e06c03601', class: "popup", part: "popup", hidden: !this.expanded, ref: element => this.popup = element }, h("div", { key: '1d73de1dabb6eaa95af12f2af88dac74e3f163ea', 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: 'a0aaafa2f4ff79efa954ed780f3a7bd81d4b2ecd', 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: '53a6706fc2c26097948b08cf0a7ee6040e37fe57', name: "create" }, "Create \u201C", this.raw, "\u201D"))), this.loading ? h("div", { class: "message" }, h("slot", { name: "loading" }, "Loading suggestions\u2026"))
+            } }, h("span", { key: '7d3b10a765ee0a6c40d7b0b49e98c676a5837944', "aria-hidden": "true" }, "\u2304"))), this.help && h("ui-tooltip", { key: 'efff00f45dc281b727789eb2aa84ff772bb5c925', id: "help-text", for: "help", toggleOnClick: true, onOpen: () => this.helpOpen = true, onClose: () => this.helpOpen = false }, this.help), h("div", { key: '770bc12b873026b571bd3ae2a80416e8af52b8d4', class: "popup", part: "popup", hidden: !this.expanded, ref: element => this.popup = element }, h("div", { key: 'ed48c8dd8b672a577d567ca5e795b8a53fde2761', 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: '43215f449bbccde407ef818cee473f69870f6f8c', 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: '3ff70ff3ab8e24afc369a26e8474e7d1220ed6eb', 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("slot", { key: '7997a0233a3c1a560b820c846645405ec4ceec1d', name: "footer" })), h("div", { key: '9143eb79141f5f3660a63f7a2471d1eecd8e9332', id: "validation", class: "message", part: "validation", hidden: !this.validation.issues.length }, this.validation.issues.map(issue => h("div", null, issue.message))), h("div", { key: '21f310613b058f528f8c4df329864fd8a2a94b55', 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(' ')));
+                : !this.rows.length && !this.canCreate ? h("div", { class: "message" }, h("slot", { name: "empty" }, "No suggestions.")) : null, h("slot", { key: '8b1fbd4f5c372393d294d8c218ae1785e6b0334f', name: "footer" })), h("div", { key: '18e68687f04e35535edee363683523ce6bbb0291', id: "validation", class: "message", part: "validation", hidden: !this.validation.issues.length }, this.validation.issues.map(issue => h("div", null, issue.message))), h("div", { key: 'e4a7db06abcfaf08b8ac592107531a13ef3a5897', 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"; }
@@ -528,15 +688,22 @@ export class UICombobox {
                 "type": "string",
                 "mutable": false,
                 "complexType": {
-                    "original": "string | null",
-                    "resolved": "string",
-                    "references": {}
+                    "original": "string | null | readonly MultiComboboxItem[]",
+                    "resolved": "readonly MultiComboboxItem[] | string",
+                    "references": {
+                        "MultiComboboxItem": {
+                            "location": "import",
+                            "path": "../../field/multi-combobox",
+                            "id": "src/field/multi-combobox.ts::MultiComboboxItem",
+                            "referenceLocation": "MultiComboboxItem"
+                        }
+                    }
                 },
                 "required": false,
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Controlled canonical value. Undefined selects uncontrolled mode; null means no selection."
+                    "text": "Controlled canonical value. Undefined selects uncontrolled mode; null means no selection.\nWith `multiple`, this is the controlled list of selected items instead."
                 },
                 "getter": false,
                 "setter": false,
@@ -562,6 +729,44 @@ export class UICombobox {
                 "reflect": false,
                 "attribute": "default-value"
             },
+            "multiple": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Render selected values as removable chips before the cursor. `value` becomes the item list."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "multiple",
+                "defaultValue": "false"
+            },
+            "tokenSeparators": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "readonly string[]",
+                    "resolved": "readonly string[]",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Characters that commit the current query and leave the input ready for the next item (multiple only)."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "[]"
+            },
             "query": {
                 "type": "string",
                 "mutable": false,
@@ -826,17 +1031,23 @@ export class UICombobox {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Single mode: the ComboboxChange. Multiple mode: the full current item list on any change."
                 },
                 "complexType": {
-                    "original": "ComboboxChange",
-                    "resolved": "ComboboxChange",
+                    "original": "ComboboxChange | readonly MultiComboboxItem[]",
+                    "resolved": "ComboboxChange | readonly MultiComboboxItem[]",
                     "references": {
                         "ComboboxChange": {
                             "location": "import",
                             "path": "../../field/combobox",
                             "id": "src/field/combobox.ts::ComboboxChange",
                             "referenceLocation": "ComboboxChange"
+                        },
+                        "MultiComboboxItem": {
+                            "location": "import",
+                            "path": "../../field/multi-combobox",
+                            "id": "src/field/multi-combobox.ts::MultiComboboxItem",
+                            "referenceLocation": "MultiComboboxItem"
                         }
                     }
                 }
@@ -950,6 +1161,72 @@ export class UICombobox {
                         }
                     }
                 }
+            }, {
+                "method": "addItem",
+                "name": "add-item",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Multiple mode: a suggestion or exact-match token was committed as a new item."
+                },
+                "complexType": {
+                    "original": "MultiComboboxItemChange",
+                    "resolved": "MultiComboboxItemChange",
+                    "references": {
+                        "MultiComboboxItemChange": {
+                            "location": "import",
+                            "path": "../../field/multi-combobox",
+                            "id": "src/field/multi-combobox.ts::MultiComboboxItemChange",
+                            "referenceLocation": "MultiComboboxItemChange"
+                        }
+                    }
+                }
+            }, {
+                "method": "removeItem",
+                "name": "remove-item",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Multiple mode: a selected item was removed via chip keyboard controls."
+                },
+                "complexType": {
+                    "original": "MultiComboboxItemChange",
+                    "resolved": "MultiComboboxItemChange",
+                    "references": {
+                        "MultiComboboxItemChange": {
+                            "location": "import",
+                            "path": "../../field/multi-combobox",
+                            "id": "src/field/multi-combobox.ts::MultiComboboxItemChange",
+                            "referenceLocation": "MultiComboboxItemChange"
+                        }
+                    }
+                }
+            }, {
+                "method": "createItem",
+                "name": "create-item",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Multiple mode: an unmatched query was submitted for creation."
+                },
+                "complexType": {
+                    "original": "MultiComboboxCreate",
+                    "resolved": "MultiComboboxCreate",
+                    "references": {
+                        "MultiComboboxCreate": {
+                            "location": "import",
+                            "path": "../../field/multi-combobox",
+                            "id": "src/field/multi-combobox.ts::MultiComboboxCreate",
+                            "referenceLocation": "MultiComboboxCreate"
+                        }
+                    }
+                }
             }];
     }
     static get methods() {

package/dist/collection/components/ui-context-menu/ui-context-menu.js

@@ -212,7 +212,7 @@ export class UIContextMenu {
         this.closeMenu('action', 'pointer');
     };
     render() {
-        return (h(Host, { key: '292937da8010dc741e3e845b6f7fd0fef6b8bda3', "data-open": this.internalOpen ? '' : undefined, "data-focus-trigger": this.internalOpen ? this.focusTrigger : undefined, onKeyDown: this.onKeydown, onClick: this.onItemClick }, h("slot", { key: '4f08876237d1919803200226d956e67de35fffab', name: "trigger" }), h("div", { key: 'c2cc0218165d02cc4c7fd11bdc52a51d39897546', class: "menu", "data-open": this.internalOpen ? '' : undefined }, h("ui-menu", { key: '1c2c6e62c86f3a38f014976843f3354d312d0744', open: this.internalOpen }, h("slot", { key: 'baeca960ac6d2277a60dc567f6e4110904d67b5e' })))));
+        return (h(Host, { key: 'aaf9f27402b0c88cede3847ee9c8f61ac844f889', "data-open": this.internalOpen ? '' : undefined, "data-focus-trigger": this.internalOpen ? this.focusTrigger : undefined, onKeyDown: this.onKeydown, onClick: this.onItemClick }, h("slot", { key: 'd801d564ec2ee073e517cb991c26efc61d3e499d', name: "trigger" }), h("div", { key: '4febcc5d76c79c2e5361db7b203e971582197fd2', class: "menu", "data-open": this.internalOpen ? '' : undefined }, h("ui-menu", { key: '7aace2479a8014a20da35f69bd3ed57b402f9ef2', open: this.internalOpen }, h("slot", { key: 'a31d703c437cf5d9ab82e5f7793caa093a312dfd' })))));
     }
     static get is() { return "ui-context-menu"; }
     static get encapsulation() { return "shadow"; }

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

@@ -104,7 +104,7 @@ export class UIDialog {
             this.accessibleLabel = nextLabel;
     };
     render() {
-        return (h(Host, { key: 'f5b4441f54505e40851dd239d12cf8ed09daabfe', "data-open": this.internalOpen ? '' : undefined, onKeyDown: this.onKeydown }, h("dialog", { key: '6896de6166cc085d9bd581dc053705fbce6328d8', ref: (el) => (this.dialogRef = el), open: this.internalOpen, "aria-label": this.accessibleLabel }, h("slot", { key: '07515a7b8da25ccbd18bcde226129a569c999af7' }))));
+        return (h(Host, { key: 'b606ef8c95728b5538047a7134030455fedf69e4', "data-open": this.internalOpen ? '' : undefined, onKeyDown: this.onKeydown }, h("dialog", { key: '85531d82c36e79230cbb22c105ff3821f1f35f58', ref: (el) => (this.dialogRef = el), open: this.internalOpen, "aria-label": this.accessibleLabel }, h("slot", { key: '8216096bc94e8261680664398691b8ea877daa0f' }))));
     }
     static get is() { return "ui-dialog"; }
     static get encapsulation() { return "shadow"; }

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

@@ -88,7 +88,7 @@ export class UIDisclosure {
         this.setOpen(!this.internalOpen, { reason: 'action', trigger: 'keyboard' });
     };
     render() {
-        return (h(Host, { key: '5c49c41703850437e8b3a1476f3333da83a4f133' }, h("slot", { key: '9a4856ad2ab237331b8485f6c3a423a43ddceb8d' })));
+        return (h(Host, { key: '91d1df53268f18c8c15192fb66b67baa7053fe93' }, h("slot", { key: '578c99f8fd09415c5e63e9f6a860fe204471da2f' })));
     }
     static get is() { return "ui-disclosure"; }
     static get encapsulation() { return "shadow"; }

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

@@ -36,9 +36,9 @@ export class UIEditable {
     }
     focusEditor() {
         const editRoot = this.host.querySelector('[slot="edit"]');
-        const candidate = editRoot?.matches('input, textarea, select, button, [tabindex], ui-combobox, ui-multi-combobox')
+        const candidate = editRoot?.matches('input, textarea, select, button, [tabindex], ui-combobox')
             ? editRoot
-            : editRoot?.querySelector('input, textarea, select, button, [tabindex], ui-combobox, ui-multi-combobox');
+            : editRoot?.querySelector('input, textarea, select, button, [tabindex], ui-combobox');
         const focusInput = candidate?.focusInput;
         if (typeof focusInput === 'function')
             void focusInput.call(candidate);
@@ -79,7 +79,7 @@ export class UIEditable {
         this.requestEdit(false, 'light-dismiss', 'pointer');
     };
     render() {
-        return h(Host, { key: '7f0c77aa06281c94407af1f060f5f2b2c34af394', "data-edit": this.internalEdit ? '' : undefined, "data-disabled": this.disabled ? '' : undefined, onClick: this.onClick, onKeyDown: this.onKeyDown }, h("div", { key: '4dc13c26dc4080ed0ad972aa677d9e844a0e7597', part: "preview", hidden: this.internalEdit }, h("slot", { key: '8332efed99f05173030d379088e8e97746f32ce6', name: "preview" })), h("div", { key: 'ec3e11ec9218077da5f17a0c724cfab17d56fb17', part: "edit", hidden: !this.internalEdit }, h("slot", { key: '46a4618614c6e55c0015d97e687a0f28e05eef38', name: "edit" })));
+        return h(Host, { key: 'c11babe81053ecc0fb6390507f74d5094c551f48', "data-edit": this.internalEdit ? '' : undefined, "data-disabled": this.disabled ? '' : undefined, onClick: this.onClick, onKeyDown: this.onKeyDown }, h("div", { key: 'fbb13fda25a177ff62f4bbb16b8fa7a8d1bfefb6', part: "preview", hidden: this.internalEdit }, h("slot", { key: '29537eed3c19da07a61b0236a563912eec332572', name: "preview" })), h("div", { key: 'a8cdb53c61041361ff97762bdf1e8e6992706751', part: "edit", hidden: !this.internalEdit }, h("slot", { key: '466c6bf07d44ab07ccab1fd138412e43a291dcca', name: "edit" })));
     }
     static get is() { return "ui-editable"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/ui-floating-action-button/ui-floating-action-button.js

@@ -4,7 +4,7 @@ export class UIFloatingActionButton {
     mobileOnly = false;
     label = '';
     render() {
-        return (h(Host, { key: '86f7c100efe7fdf900de7abbcc1a01c475b0da1d', "data-disabled": this.disabled ? '' : undefined }, h("button", { key: '91398faeb693dcbe11d58e59a183391ce6e4876c', type: "button", "aria-label": this.label || undefined, disabled: this.disabled }, h("slot", { key: 'd11b6f638b045d6835279f3381442983b40472d9' }))));
+        return (h(Host, { key: '54f6284109397d15e2b3ef92f68e9bd4cf91fbae', "data-disabled": this.disabled ? '' : undefined }, h("button", { key: '9ebad7e3bbc2bf18d4d5a04f37a9f2d77011ad34', type: "button", "aria-label": this.label || undefined, disabled: this.disabled }, h("slot", { key: '222c6807ae4639eb20dc25be08fe5f4e91c638de' }))));
     }
     static get is() { return "ui-floating-action-button"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/ui-form-field/ui-form-field.js

@@ -98,7 +98,7 @@ export class UIFormField {
         input.setAttribute('aria-invalid', this.invalid ? 'true' : 'false');
     }
     render() {
-        return (h(Host, { key: '3d331f3506c3853d751395569e87614c52ce0076', "data-invalid": this.invalid ? '' : undefined, "data-disabled": this.disabled ? '' : undefined, "data-required": this.required ? '' : undefined }, h("slot", { key: '1b582b4961a767230b19efa314943f8a5426270e', onSlotchange: this.scheduleWire })));
+        return (h(Host, { key: 'f052dbf0ba289bf187ea78c458260110fbfa059a', "data-invalid": this.invalid ? '' : undefined, "data-disabled": this.disabled ? '' : undefined, "data-required": this.required ? '' : undefined }, h("slot", { key: 'f26f48581b5781e8c3d7830ddd3707ea4fb04420', onSlotchange: this.scheduleWire })));
     }
     static get is() { return "ui-form-field"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/ui-icon-button/ui-icon-button.js

@@ -7,7 +7,7 @@ export class UIIconButton {
     /** Reveals this control through a surrounding ui-affordance-scope. */
     anticipatory = false;
     render() {
-        return (h(Host, { key: '9e8ee3ff8c9f9ab5113a7635e49755e0eb998898', "data-disabled": this.disabled ? '' : undefined, "data-ui-affordance": this.anticipatory ? 'button' : undefined }, h("button", { key: '7f6dd5ae40b595634ba91834c2bb113687ee5cb8', type: "button", "aria-label": this.label || undefined, disabled: this.disabled }, h("slot", { key: 'c7a94d7fb54fbff44e372bf4f67bb29a40bfc45b' }))));
+        return (h(Host, { key: '8d0f84c9d3aaa69f47430369b511bb4160de5cc8', "data-disabled": this.disabled ? '' : undefined, "data-ui-affordance": this.anticipatory ? 'button' : undefined }, h("button", { key: 'b896cdb091e9733b2b8625463f1324819c23965c', type: "button", "aria-label": this.label || undefined, disabled: this.disabled }, h("slot", { key: '76ab5e5f4d34e3f0850287b4552dde060b3798e7' }))));
     }
     static get is() { return "ui-icon-button"; }
     static get encapsulation() { return "shadow"; }

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

@@ -70,7 +70,7 @@ export class UIInput {
         });
     };
     render() {
-        return (h(Host, { key: '90597a900e0504f0e729990dd8cbc84c35d8162f', "data-invalid": this.invalid ? '' : undefined }, h("slot", { key: '1c8ac0ad7e4d3a5a9b913c2687021ef7037ccfa7', ref: (el) => (this.slotRef = el) })));
+        return (h(Host, { key: '92505de6b1245569a6d4746418a70f8d7bc4eed9', "data-invalid": this.invalid ? '' : undefined }, h("slot", { key: 'd5743dc62037b5d7722cfbb64a582592327c75e5', ref: (el) => (this.slotRef = el) })));
     }
     static get is() { return "ui-input"; }
     static get encapsulation() { return "shadow"; }

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

@@ -153,7 +153,7 @@ export class UIMenu {
         }
     };
     render() {
-        return (h(Host, { key: '22689ca1b0514bb27a76bfb9a702c0d4ce49d136', role: "menu", "aria-orientation": "vertical", "data-open": this.internalOpen ? '' : undefined }, h("div", { key: 'cff891a33348f077631f1b92f1167285aafd25f1', class: "menu__surface" }, h("slot", { key: '3a0e9ff4f36b1afbe5f879e0e51ff4943279b5b5' }))));
+        return (h(Host, { key: '5b64cc53ca56ea04a63013c8cb61231c9b1045cc', role: "menu", "aria-orientation": "vertical", "data-open": this.internalOpen ? '' : undefined }, h("div", { key: '6410a56cc5efcffd0673c9abdf8f8aa45295c516', class: "menu__surface" }, h("slot", { key: '7e7f9d3b19bbf3024d61ecf44cd8b103748ef966' }))));
     }
     static get is() { return "ui-menu"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/ui-menu-item/ui-menu-item.js

@@ -3,7 +3,7 @@ export class UIMenuItem {
     disabled = false;
     value = '';
     render() {
-        return (h(Host, { key: '856cf07264b2eb8e3e51305408855156e11d9a8b', role: "menuitem", tabIndex: this.disabled ? -1 : 0, "aria-disabled": this.disabled ? 'true' : undefined, "data-value": this.value || undefined }, h("span", { key: 'a56401f9b910175eb5683d1748f323dce0d55a9c', class: "menu-item__surface" }, h("slot", { key: '4ee22fd4cdb10ec822e4485e48ed8000a10512ae' }))));
+        return (h(Host, { key: 'd0f0886b18ebd01c0c2e20a2c1b1ecfd57eeb3e3', role: "menuitem", tabIndex: this.disabled ? -1 : 0, "aria-disabled": this.disabled ? 'true' : undefined, "data-value": this.value || undefined }, h("span", { key: '7fc584fb670b5b8ce0bbd3be1fea08f87de4a298', class: "menu-item__surface" }, h("slot", { key: '066fb08bc22996d439f3216e401a93a084e3e299' }))));
     }
     static get is() { return "ui-menu-item"; }
     static get encapsulation() { return "shadow"; }

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

@@ -105,7 +105,7 @@ export class UIPopover {
         }
     };
     render() {
-        return (h(Host, { key: 'f63907b8e49b8264c291048c509b6164fdd60ca4', "data-open": this.internalOpen ? '' : undefined, onKeyDown: this.onKeydown }, h("div", { key: '2425f4394749d994693f4a256256bd9e2f5daf60', class: "popover__surface" }, h("slot", { key: '3b6f925da371d43e828842c4027cddee673d7ab3' }))));
+        return (h(Host, { key: '65a0927abc40450205989704bfde2cf7fd80d1f9', "data-open": this.internalOpen ? '' : undefined, onKeyDown: this.onKeydown }, h("div", { key: '255acaf99e0fe70a92048351b24bdfde1a4ea45f', class: "popover__surface" }, h("slot", { key: '9d2f6c9d5a0f7a2766225aef0ec5b98b33ec9f07' }))));
     }
     static get is() { return "ui-popover"; }
     static get encapsulation() { return "shadow"; }

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

@@ -62,7 +62,7 @@ export class UIRadio {
         });
     };
     render() {
-        return (h(Host, { key: '5bab1394b8238609e4382309e4b11bca82a60b12', role: "radio", "aria-checked": String(this.internalChecked), "aria-disabled": String(this.disabled), "data-disabled": this.disabled ? '' : undefined }, h("slot", { key: '56ba5b7ec4ab53299c66689558338d2c6ab3e4f6', ref: (el) => (this.slotRef = el) })));
+        return (h(Host, { key: '32df72dff7253956875ef28f593462ddbbb90eef', role: "radio", "aria-checked": String(this.internalChecked), "aria-disabled": String(this.disabled), "data-disabled": this.disabled ? '' : undefined }, h("slot", { key: '0c78f3e3bdf4d618547b267128c6fc0fdd651599', ref: (el) => (this.slotRef = el) })));
     }
     static get is() { return "ui-radio"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/ui-radio-group/ui-radio-group.js

@@ -102,7 +102,7 @@ export class UIRadioGroup {
         }
     };
     render() {
-        return (h(Host, { key: '31d8dee04aad4ddbb0bfa617a4e6ed187eab6674', role: "radiogroup", "aria-orientation": this.orientation, "data-orientation": this.orientation, "data-disabled": this.disabled ? '' : undefined }, h("slot", { key: '7134bcfa6b11cbe0d0d55a6593ea3fca921a71ec' })));
+        return (h(Host, { key: '9bdfe6b5209b5444cb27dde3226ec33866999c25', role: "radiogroup", "aria-orientation": this.orientation, "data-orientation": this.orientation, "data-disabled": this.disabled ? '' : undefined }, h("slot", { key: 'b81a2f1e4c49000cfb5357570b460564ced48d91' })));
     }
     static get is() { return "ui-radio-group"; }
     static get encapsulation() { return "shadow"; }