@pitchfork-ui/elements 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,713 @@
+import { composeDescribedBy, findTypeaheadMatch, getEnabledIndexes, isActivationKey, Keys, nextTypeaheadBuffer, observeAnchoredPosition, resolveListMove, TYPEAHEAD_TIMEOUT_MS, isTypeaheadKey, } 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 single-choice select over `pf-option` children.
+ *
+ * The first of Wave 5, and the worked example for §2.1: the options are child
+ * elements, so a label is a slot and can hold anything, where the React
+ * `Select`'s `options` array can only hold a string.
+ *
+ * **It has typeahead, which the React component does not.** Typing `b` jumps
+ * to the next option beginning with `b`, `br` narrows, and `bbb` cycles — the
+ * ARIA listbox pattern, and the matching is core's so a later `pf-combobox`
+ * answers the same keystrokes. `todo.md` has the React fix.
+ *
+ * Form-associated, so the value submits by itself. The React component fakes
+ * that with a hidden `<input>` beside the trigger.
+ *
+ * The active option is set as an *element*, not an IDREF: the trigger is in
+ * this shadow root and the options are slotted light DOM, and a cross-root
+ * IDREF is absent from the accessibility tree — measured. `aria-controls` does
+ * work, because the listbox itself is in this same root.
+ *
+ * @slot - the `pf-option` children.
+ * @part field - the wrapper around label, control and messages.
+ * @part label - the label element.
+ * @part trigger - the combobox button.
+ * @part listbox - the floating listbox the options are slotted into.
+ * @part description - the hint text below the control.
+ * @part error - the error message below the control.
+ */
+export class PfSelect {
+    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 = 'Select an option';
+    required = false;
+    disabled = false;
+    /** Options to show before the listbox scrolls. Unset means it fits them all. */
+    maxVisibleOptions;
+    /** Fires when the chosen value changes. */
+    pfChange;
+    /** Fires whenever the listbox opens or closes, whoever caused it. */
+    pfOpenChange;
+    /** The label of the chosen option, for the trigger to show. */
+    selectedLabel = '';
+    initialValue = '';
+    stopObserving;
+    activeOption = null;
+    typeahead = '';
+    typeaheadTimer;
+    componentWillLoad() {
+        this.initialValue = this.value ?? '';
+        this.syncFormState();
+        this.syncOptions();
+    }
+    componentDidRender() {
+        this.syncActiveDescendant();
+    }
+    disconnectedCallback() {
+        this.stopObserving?.();
+        if (this.typeaheadTimer)
+            clearTimeout(this.typeaheadTimer);
+    }
+    syncFormState() {
+        this.internals.setFormValue(this.value || null);
+        applyControlValidity(this.internals, Boolean(this.value), this.required, this.error);
+    }
+    /** The value changed, so the children's `selected` and the trigger follow. */
+    syncOptions() {
+        const options = this.options();
+        let label = '';
+        for (const option of options) {
+            const selected = this.optionValue(option) === this.value && this.value !== '';
+            option.selected = selected;
+            if (selected)
+                label = option.textContent?.trim() ?? '';
+        }
+        this.selectedLabel = label;
+    }
+    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;
+    }
+    /** A reset restores the value the control started with, not an empty one. */
+    formResetCallback() {
+        this.value = this.initialValue;
+    }
+    /** An option added or removed while mounted; re-mark the children. */
+    onSlotChange = () => {
+        this.syncOptions();
+    };
+    /** Re-reads the options, for a label edited in place (which fires no slotchange). */
+    async refresh() {
+        this.syncOptions();
+    }
+    options() {
+        return Array.from(this.el.querySelectorAll('pf-option'));
+    }
+    enabled() {
+        return this.options().filter((option) => !option.hasAttribute('disabled'));
+    }
+    /** The property, never the attribute: a binding may only have set the former. */
+    optionValue(option) {
+        return option.value ?? option.getAttribute('value') ?? '';
+    }
+    get listbox() {
+        return this.el.shadowRoot?.querySelector('[part="listbox"]') ?? null;
+    }
+    get trigger() {
+        return this.el.shadowRoot?.querySelector('[part="trigger"]') ?? null;
+    }
+    showListbox() {
+        const panel = this.listbox;
+        if (this.disabled || !panel || panel.matches(':popover-open'))
+            return;
+        panel.showPopover();
+        this.stopObserving?.();
+        this.stopObserving = observeAnchoredPosition({
+            getAnchor: () => this.trigger,
+            getFloating: () => panel,
+            // The listbox matches the trigger's width, as the React component does.
+            matchAnchorWidth: true,
+            flip: true,
+            /*
+             * `width` *and* `minWidth`: core reports whichever the mode calls for
+             * and leaves the other undefined — `matchAnchorWidth: true` gives a
+             * `width`, false gives a `minWidth`. Reading only `minWidth`, which is
+             * what pf-dropdown needs, left the listbox at its intrinsic 156px beside
+             * a 1216px trigger. The smoke test against a real build caught it.
+             */
+            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`;
+            },
+        });
+        /*
+         * Opens on the chosen option, or the first selectable one. Landing
+         * anywhere else would make the arrows start from somewhere the user has
+         * no reason to expect.
+         */
+        const options = this.options();
+        const chosen = options.find((option) => this.optionValue(option) === this.value);
+        this.setActive(chosen && !chosen.hasAttribute('disabled') ? chosen : (this.enabled()[0] ?? null));
+    }
+    hideListbox() {
+        this.stopObserving?.();
+        this.stopObserving = undefined;
+        this.clearTypeahead();
+        const panel = this.listbox;
+        if (panel?.matches(':popover-open'))
+            panel.hidePopover();
+    }
+    onToggle = (event) => {
+        const nowOpen = event.newState === 'open';
+        if (this.open !== nowOpen)
+            this.open = nowOpen;
+        if (!nowOpen)
+            this.trigger?.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' });
+        }
+    }
+    /**
+     * Feature-detected. Where ARIA element reflection is missing there is no
+     * cross-root equivalent, so the active option stops being *announced* while
+     * the arrows and Enter still work — recorded in `todo.md`.
+     */
+    syncActiveDescendant() {
+        const trigger = this.trigger;
+        if (!trigger || !('ariaActiveDescendantElement' in trigger))
+            return;
+        trigger.ariaActiveDescendantElement = this.open ? this.activeOption : null;
+    }
+    commit(option) {
+        if (option.hasAttribute('disabled'))
+            return;
+        const next = this.optionValue(option);
+        this.open = false;
+        this.trigger?.focus();
+        if (next === this.value)
+            return;
+        this.value = next;
+        this.pfChange.emit({ value: next });
+    }
+    /** An option asked to be taken. The select decides, reports and closes. */
+    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 options = this.options();
+        const enabledIndexes = getEnabledIndexes(options, (option) => option.hasAttribute('disabled'));
+        const current = this.activeOption ? options.indexOf(this.activeOption) : -1;
+        const next = resolveListMove(action, enabledIndexes, current);
+        if (next !== -1)
+            this.setActive(options[next] ?? null);
+    }
+    clearTypeahead() {
+        if (this.typeaheadTimer)
+            clearTimeout(this.typeaheadTimer);
+        this.typeaheadTimer = undefined;
+        this.typeahead = '';
+    }
+    /**
+     * Typeahead. The buffer and its timer live here, because a timer is state
+     * and core is never a state container; the matching is core's.
+     */
+    handleTypeahead(key) {
+        this.typeahead = nextTypeaheadBuffer(this.typeahead, key);
+        if (this.typeaheadTimer)
+            clearTimeout(this.typeaheadTimer);
+        this.typeaheadTimer = setTimeout(() => this.clearTypeahead(), TYPEAHEAD_TIMEOUT_MS);
+        const options = this.options();
+        const labels = options.map((option) => option.textContent ?? '');
+        const from = this.activeOption ? options.indexOf(this.activeOption) : -1;
+        const match = findTypeaheadMatch(labels, this.typeahead, from, (index) => options[index].hasAttribute('disabled'));
+        if (match === -1)
+            return;
+        /*
+         * Closed, typeahead *chooses* rather than merely highlighting: that is
+         * what a native `<select>` does, and with no listbox on screen a
+         * highlight nobody can see would be no feedback at all.
+         */
+        if (this.open)
+            this.setActive(options[match]);
+        else
+            this.commit(options[match]);
+    }
+    handleKeyDown(event) {
+        if (this.disabled || event.defaultPrevented)
+            return;
+        const move = MOVES[event.key];
+        if (move) {
+            event.preventDefault();
+            // Down or Up on a closed select opens it, as a combobox should.
+            if (!this.open)
+                this.open = true;
+            else
+                this.move(move);
+            return;
+        }
+        if (isActivationKey(event.key)) {
+            event.preventDefault();
+            if (!this.open) {
+                this.open = true;
+            }
+            else if (this.activeOption) {
+                this.commit(this.activeOption);
+            }
+            return;
+        }
+        // Escape is the browser's while the listbox is a `popover="auto"`.
+        if (isTypeaheadKey(event.key)) {
+            event.preventDefault();
+            this.handleTypeahead(event.key);
+        }
+    }
+    render() {
+        const describedBy = composeDescribedBy(this.description && 'description', this.error && 'error');
+        return (h(Host, { key: 'ccb96054293516751523dc6b89d3fd3bb3e08902' }, h("div", { key: '65d6ca23015f8371f02715f1b3cf862122c94932', class: "field", part: "field" }, this.label && (h("label", { key: '580a891de1e1c60481a494ab5f915e0c8528d511', class: "label", part: "label", htmlFor: "trigger" }, this.label, this.required && (h("span", { key: 'dd0e347bcfafdca6eba7dc06f596215b47331e8f', class: "required", "aria-hidden": "true" }, "*")))), h("button", { key: '7c6b543a99a06b9d18a6339e0aa3c6ad3d2eb260', id: "trigger", "aria-label": controlAriaLabel(this.el, this.label), part: "trigger", class: { trigger: true, 'trigger--invalid': Boolean(this.error) }, type: "button", role: "combobox", disabled: this.disabled, "aria-haspopup": "listbox", "aria-expanded": this.open ? 'true' : 'false', "aria-controls": "listbox", "aria-invalid": this.error ? 'true' : null, "aria-required": this.required ? 'true' : null, "aria-describedby": describedBy, onClick: () => {
+                if (!this.disabled)
+                    this.open = !this.open;
+            } }, h("span", { key: '032fb5d8de622dde393a5100ce69d08944916bb9', class: { value: true, 'value--placeholder': !this.selectedLabel } }, this.selectedLabel || this.placeholder), h("span", { key: 'eae5f550a6b4f16a27a044220db57236aebd31b8', class: "chevron", "aria-hidden": "true" }, h("pf-icon", { key: '7983ac569e121be6a98822cdbec4c46ae43dc99e', name: "chevron-down" }))), this.description && (h("p", { key: 'c27fc89569900855af8966fcec3246f7f12c1d20', class: "description", part: "description", id: "description" }, this.description)), this.error && (h("p", { key: '6d805181ffb58622ed41e688195bdf58511e7efa', class: "error", part: "error", id: "error" }, this.error))), h("div", { key: '2dbc1adeaf68449ffaf32fc07d694d4c66860e90', id: "listbox", part: "listbox", class: "listbox", popover: "auto", role: "listbox", "aria-label": this.label ?? this.placeholder, style: this.maxVisibleOptions
+                ? { maxHeight: `calc(${this.maxVisibleOptions} * 36px)`, overflowY: 'auto' }
+                : undefined, onToggle: this.onToggle }, h("slot", { key: '02373173990a5e9ecad005b21f1a4b11d2cef032', onSlotchange: this.onSlotChange }))));
+    }
+    static get is() { return "pf-select"; }
+    static get encapsulation() { return "shadow"; }
+    static get formAssociated() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["pf-select.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["pf-select.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": "'Select an option'"
+            },
+            "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"
+            },
+            "maxVisibleOptions": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Options to show before the listbox scrolls. Unset means it fits them all."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max-visible-options"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "selectedLabel": {}
+        };
+    }
+    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 (which fires no slotchange).",
+                    "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": "syncOptions"
+            }, {
+                "propName": "open",
+                "methodName": "syncOpen"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "pfOptionSelect",
+                "method": "handleOptionSelect",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "keydown",
+                "method": "handleKeyDown",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }];
+    }
+    static get attachInternalsMemberName() { return "internals"; }
+}
+//# sourceMappingURL=pf-select.js.map