@pitchfork-ui/elements 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,754 @@
+import { composeDescribedBy, getEnabledIndexes, Keys, matchesCommandQuery, observeAnchoredPosition, queryIsEchoedSelection, resolveListMove, } from "@pitchfork-ui/core";
+import { applyControlValidity } from "../../form-validity";
+import { controlAriaLabel } from "../../control-label";
+import { placePopover } from "../../place-popover";
+import { h, Host, } from "@stencil/core";
+const MOVES = {
+    [Keys.ArrowDown]: 'next',
+    [Keys.ArrowUp]: 'previous',
+    [Keys.Home]: 'first',
+    [Keys.End]: 'last',
+};
+/**
+ * A form-associated combobox: an editable field that filters `pf-option`
+ * children.
+ *
+ * It shares `pf-option` with `pf-select`, which is why the option reads a
+ * generic `--pf-option-*` set that each container maps to its own family —
+ * the same arrangement as `pf-menu-item` between the two menus.
+ *
+ * Filtering is core's `matchesCommandQuery`, and so is the rule that a query
+ * which is only the chosen label echoed back does not filter: without it,
+ * reopening the list to change your mind would show the one answer you already
+ * had. Both shared with the React component, which is now rewired to them.
+ *
+ * Two things the React `Combobox` does not do, both gaps rather than choices:
+ * Home and End, and arrows that wrap rather than stop at the ends — which is
+ * what `pf-select` does, and one design system should not have two arrow
+ * behaviours in neighbouring controls.
+ *
+ * @slot - the `pf-option` children.
+ * @part field - the wrapper around label, control and messages.
+ * @part label - the label element.
+ * @part control - the box holding the input, clear button and chevron.
+ * @part input - the editable field.
+ * @part clear - the clear button.
+ * @part listbox - the floating listbox the options are slotted into.
+ * @part empty - the message shown when nothing matches.
+ * @part description - the hint text below the control.
+ * @part error - the error message below the control.
+ */
+export class PfCombobox {
+    el;
+    internals;
+    /** Submitted under this name. Reflected; the submission reads the attribute. */
+    name;
+    /** The chosen option's value, or empty. */
+    value = '';
+    /** Whether the listbox is showing. Reflected for the stylesheet. */
+    open = false;
+    label;
+    description;
+    error;
+    placeholder = 'Search…';
+    /** Shown when the query matches nothing. */
+    emptyMessage = 'No matches';
+    required = false;
+    disabled = false;
+    /** Offer a button that empties the field. */
+    clearable = true;
+    /** Accessible name for that button. */
+    clearLabel = 'Clear';
+    /** Fires when the chosen value changes. */
+    pfChange;
+    /** Fires whenever the listbox opens or closes, whoever caused it. */
+    pfOpenChange;
+    /** What the field holds, which is not the value until an option is chosen. */
+    query = '';
+    matchCount = 0;
+    initialValue = '';
+    stopObserving;
+    activeOption = null;
+    componentWillLoad() {
+        this.initialValue = this.value ?? '';
+        this.syncFormState();
+        this.query = this.selectedLabel();
+        this.applyQuery();
+    }
+    componentDidRender() {
+        this.syncActiveDescendant();
+    }
+    disconnectedCallback() {
+        this.stopObserving?.();
+    }
+    syncFormState() {
+        this.internals.setFormValue(this.value || null);
+        applyControlValidity(this.internals, Boolean(this.value), this.required, this.error);
+    }
+    /** A value set from outside puts its label in the field and marks the option. */
+    syncSelection() {
+        for (const option of this.options()) {
+            option.selected =
+                this.optionValue(option) === this.value && this.value !== '';
+        }
+        this.query = this.selectedLabel();
+        this.applyQuery();
+    }
+    syncOpen(next, previous) {
+        if (next)
+            this.showListbox();
+        else
+            this.hideListbox();
+        if (next !== previous)
+            this.pfOpenChange.emit({ open: next });
+    }
+    async show() {
+        if (!this.disabled)
+            this.open = true;
+    }
+    async hide() {
+        this.open = false;
+    }
+    async checkValidity() {
+        return this.internals.checkValidity();
+    }
+    async reportValidity() {
+        return this.internals.reportValidity();
+    }
+    async getValidationMessage() {
+        return this.internals.validationMessage;
+    }
+    formResetCallback() {
+        this.value = this.initialValue;
+        this.query = this.selectedLabel();
+        this.applyQuery();
+    }
+    /** Re-reads the options, for a label edited in place (no `slotchange` fires). */
+    async refresh() {
+        this.syncSelection();
+    }
+    onSlotChange = () => {
+        this.syncSelection();
+    };
+    options() {
+        return Array.from(this.el.querySelectorAll('pf-option'));
+    }
+    visible() {
+        return this.options().filter((option) => !option.hasAttribute('hidden'));
+    }
+    /** The property, never the attribute: a binding may only have set the former. */
+    optionValue(option) {
+        return option.value ?? option.getAttribute('value') ?? '';
+    }
+    selectedLabel() {
+        const chosen = this.options().find((option) => this.optionValue(option) === this.value);
+        return this.value && chosen ? (chosen.textContent?.trim() ?? '') : '';
+    }
+    get listbox() {
+        return this.el.shadowRoot?.querySelector('[part="listbox"]') ?? null;
+    }
+    get input() {
+        return this.el.shadowRoot?.querySelector('[part="input"]') ?? null;
+    }
+    get control() {
+        return this.el.shadowRoot?.querySelector('[part="control"]') ?? null;
+    }
+    /**
+     * Hides the options the query excludes.
+     *
+     * `hidden` plus `:host([hidden]) { display: none }` on the option, because
+     * the attribute alone loses to the option's own `display: block`.
+     */
+    applyQuery() {
+        const echoed = queryIsEchoedSelection(this.query, this.selectedLabel());
+        const options = this.options();
+        for (const option of options) {
+            const matches = echoed || matchesCommandQuery({ label: option.textContent?.trim() ?? '' }, this.query);
+            if (matches)
+                option.removeAttribute('hidden');
+            else
+                option.setAttribute('hidden', '');
+        }
+        const visible = this.visible();
+        this.matchCount = visible.length;
+        // A new query starts at the top of what is left.
+        const first = visible.find((option) => !option.hasAttribute('disabled')) ?? null;
+        if (!this.activeOption || this.activeOption.hasAttribute('hidden'))
+            this.setActive(first);
+    }
+    showListbox() {
+        const panel = this.listbox;
+        if (this.disabled || !panel || panel.matches(':popover-open'))
+            return;
+        panel.showPopover();
+        this.stopObserving?.();
+        this.stopObserving = observeAnchoredPosition({
+            getAnchor: () => this.control,
+            getFloating: () => panel,
+            matchAnchorWidth: true,
+            flip: true,
+            onChange: ({ left, top, width, minWidth }) => {
+                placePopover(panel, left, top);
+                if (width !== undefined)
+                    panel.style.width = `${width}px`;
+                if (minWidth !== undefined)
+                    panel.style.minWidth = `${minWidth}px`;
+            },
+        });
+        this.applyQuery();
+    }
+    hideListbox() {
+        this.stopObserving?.();
+        this.stopObserving = undefined;
+        const panel = this.listbox;
+        if (panel?.matches(':popover-open'))
+            panel.hidePopover();
+    }
+    /**
+     * A browser-driven close — light dismiss or Escape — reverts the field to
+     * the chosen label, so a half-typed query never lingers over a different
+     * value. Focus goes back to the input rather than the trigger, because here
+     * the input *is* the control.
+     */
+    onToggle = (event) => {
+        const nowOpen = event.newState === 'open';
+        if (this.open !== nowOpen)
+            this.open = nowOpen;
+        if (!nowOpen) {
+            this.query = this.selectedLabel();
+            this.applyQuery();
+            this.input?.focus();
+        }
+    };
+    setActive(option) {
+        for (const other of this.options()) {
+            if (other !== option)
+                other.active = false;
+        }
+        if (option)
+            option.active = true;
+        this.activeOption = option;
+        this.syncActiveDescendant();
+        if (option && typeof option.scrollIntoView === 'function') {
+            option.scrollIntoView({ block: 'nearest' });
+        }
+    }
+    /**
+     * Set as an element, not an IDREF: the input is in this shadow root and the
+     * options are slotted light DOM, and a cross-root IDREF is absent from the
+     * accessibility tree — measured. Feature-detected, because where element
+     * reflection is missing there is no cross-root equivalent.
+     */
+    syncActiveDescendant() {
+        const input = this.input;
+        if (!input || !('ariaActiveDescendantElement' in input))
+            return;
+        input.ariaActiveDescendantElement = this.open ? this.activeOption : null;
+    }
+    commit(option) {
+        if (option.hasAttribute('disabled'))
+            return;
+        const next = this.optionValue(option);
+        this.open = false;
+        if (next !== this.value) {
+            this.value = next;
+            this.pfChange.emit({ value: next });
+        }
+        // Set after the value, so it is the chosen label rather than the query.
+        this.query = this.selectedLabel();
+        this.applyQuery();
+        this.input?.focus();
+    }
+    handleOptionSelect(event) {
+        event.stopPropagation();
+        if (this.disabled)
+            return;
+        const option = this.options().find((candidate) => this.optionValue(candidate) === event.detail.value);
+        if (option)
+            this.commit(option);
+    }
+    move(action) {
+        const visible = this.visible();
+        const enabledIndexes = getEnabledIndexes(visible, (option) => option.hasAttribute('disabled'));
+        const current = this.activeOption ? visible.indexOf(this.activeOption) : -1;
+        const next = resolveListMove(action, enabledIndexes, current);
+        if (next !== -1)
+            this.setActive(visible[next] ?? null);
+    }
+    onInput = (event) => {
+        this.query = event.target.value;
+        this.applyQuery();
+        if (!this.open)
+            this.open = true;
+    };
+    clear = () => {
+        this.query = '';
+        if (this.value !== '') {
+            this.value = '';
+            this.pfChange.emit({ value: '' });
+        }
+        this.applyQuery();
+        this.open = true;
+        this.input?.focus();
+    };
+    onKeyDown = (event) => {
+        if (this.disabled)
+            return;
+        const move = MOVES[event.key];
+        if (move) {
+            event.preventDefault();
+            if (!this.open)
+                this.open = true;
+            else
+                this.move(move);
+            return;
+        }
+        /*
+         * Enter only commits while the listbox is open. Closed, it is left alone
+         * so a combobox inside a form still submits it.
+         */
+        if (event.key === Keys.Enter && this.open && this.activeOption) {
+            event.preventDefault();
+            this.commit(this.activeOption);
+        }
+        // Escape is the browser's: `popover="auto"` closes, and `onToggle` reverts.
+    };
+    render() {
+        const describedBy = composeDescribedBy(this.description && 'description', this.error && 'error');
+        const showClear = this.clearable && !this.disabled && (this.query !== '' || this.value !== '');
+        return (h(Host, { key: '4a948db9316e8174c9c7592afb9912deb59eecdd' }, h("div", { key: 'ac5e469f9c00ec843fdb7a485cb3cbe9ddc08573', class: "field", part: "field" }, this.label && (h("label", { key: 'eb610c213cfe510c229f5ffa81e9761bf7303476', class: "label", part: "label", htmlFor: "input" }, this.label, this.required && (h("span", { key: 'd942137e81be6007aafe2e1dfc43e97e2ab8af59', class: "required", "aria-hidden": "true" }, "*")))), h("div", { key: 'b9f4806e7882e5dc2c64abe87f48bb925173d7dc', class: { control: true, 'control--invalid': Boolean(this.error) }, part: "control" }, h("input", { key: '9a10cc81ff212f3e279cfcc311886756d7ca76f1', id: "input", "aria-label": controlAriaLabel(this.el, this.label), part: "input", class: "input", type: "text", role: "combobox", autocomplete: "off", disabled: this.disabled, required: this.required, placeholder: this.placeholder, value: this.query, "aria-autocomplete": "list", "aria-expanded": this.open ? 'true' : 'false', "aria-controls": "listbox", "aria-invalid": this.error ? 'true' : null, "aria-describedby": describedBy, onInput: this.onInput, onKeyDown: this.onKeyDown, onClick: () => {
+                if (!this.disabled)
+                    this.open = true;
+            } }), showClear && (h("button", { key: 'bc9f8df667df57cbede3aa00a4119f6591faeb7d', class: "clear", part: "clear", type: "button", "aria-label": this.clearLabel,
+            /* Out of the tab order, so it never interrupts the keyboard flow. */
+            tabindex: -1, onMouseDown: (event) => event.preventDefault(), onClick: this.clear }, h("pf-icon", { key: '580dab29c2631f79b7a611f7dd95a81fc5cffda2', name: "circle-xmark" }))), h("span", { key: '06d06d1fcbae5937632cf2451ab97d42d1410c91', class: "chevron", "aria-hidden": "true" }, h("pf-icon", { key: 'd30dd0a5d008cec99c1ec8fd25acc7fdfbdd68db', name: "chevron-down" }))), this.description && (h("p", { key: '09873008049536bb2eab61825ae95a2d92e3952a', class: "description", part: "description", id: "description" }, this.description)), this.error && (h("p", { key: 'ee43b1e024ff0e6e052054278680e04651b55421', class: "error", part: "error", id: "error" }, this.error))), h("div", { key: '5b221c6566bc6dd29dc3a5d9ee5268ec65fa296e', id: "listbox", part: "listbox", class: "listbox", popover: "auto", role: "listbox", "aria-label": this.label ?? this.placeholder, onToggle: this.onToggle }, h("slot", { key: '645c56c8dd776ddd013be68c2bfc544f35c05b35', onSlotchange: this.onSlotChange }), this.matchCount === 0 && (h("p", { key: '9a3aac572c41177b41be06f9986d0718756c7de3', class: "empty", part: "empty" }, this.emptyMessage)))));
+    }
+    static get is() { return "pf-combobox"; }
+    static get encapsulation() { return "shadow"; }
+    static get formAssociated() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["pf-combobox.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["pf-combobox.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "name": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Submitted under this name. Reflected; the submission reads the attribute."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "name"
+            },
+            "value": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "The chosen option's value, or empty."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "value",
+                "defaultValue": "''"
+            },
+            "open": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Whether the listbox is showing. Reflected for the stylesheet."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "open",
+                "defaultValue": "false"
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label"
+            },
+            "description": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "description"
+            },
+            "error": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "error"
+            },
+            "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": "'Search\u2026'"
+            },
+            "emptyMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Shown when the query matches nothing."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "empty-message",
+                "defaultValue": "'No matches'"
+            },
+            "required": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "required",
+                "defaultValue": "false"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "clearable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Offer a button that empties the field."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "clearable",
+                "defaultValue": "true"
+            },
+            "clearLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Accessible name for that button."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "clear-label",
+                "defaultValue": "'Clear'"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "query": {},
+            "matchCount": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "pfChange",
+                "name": "pfChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fires when the chosen value changes."
+                },
+                "complexType": {
+                    "original": "{ value: string }",
+                    "resolved": "{ value: string; }",
+                    "references": {}
+                }
+            }, {
+                "method": "pfOpenChange",
+                "name": "pfOpenChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fires whenever the listbox opens or closes, whoever caused it."
+                },
+                "complexType": {
+                    "original": "{ open: boolean }",
+                    "resolved": "{ open: boolean; }",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "show": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "hide": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "checkValidity": {
+                "complexType": {
+                    "signature": "() => Promise<boolean>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "reportValidity": {
+                "complexType": {
+                    "signature": "() => Promise<boolean>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "getValidationMessage": {
+                "complexType": {
+                    "signature": "() => Promise<string>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<string>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "refresh": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Re-reads the options, for a label edited in place (no `slotchange` fires).",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "value",
+                "methodName": "syncFormState"
+            }, {
+                "propName": "error",
+                "methodName": "syncFormState"
+            }, {
+                "propName": "required",
+                "methodName": "syncFormState"
+            }, {
+                "propName": "value",
+                "methodName": "syncSelection"
+            }, {
+                "propName": "open",
+                "methodName": "syncOpen"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "pfOptionSelect",
+                "method": "handleOptionSelect",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }];
+    }
+    static get attachInternalsMemberName() { return "internals"; }
+}
+//# sourceMappingURL=pf-combobox.js.map