@pitchfork-ui/elements 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,691 @@
+import { composeDescribedBy, formatValueList, getEnabledIndexes, isActivationKey, Keys, observeAnchoredPosition, parseValueList, resolveListMove, toggleValueInList, assertSeparableValues, } from "@pitchfork-ui/core";
+import { applyControlValidity } from "../../form-validity";
+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 multi-choice select over `pf-option` children.
+ *
+ * **It submits one entry per chosen value from a single control.**
+ * `setFormValue` takes a `FormData`, and a key repeated in it is submitted
+ * once per value — measured, and the same shape the React component gets from
+ * rendering one hidden `<input>` per selection. So a server reads
+ * `data.getAll(name)` exactly as it would from a native multiple select.
+ *
+ * `value` is one comma-separated string, because that is what an attribute can
+ * carry; `pfChange` also reports the parsed `values` array, which is what a
+ * framework consumer usually wants. A value containing a comma cannot survive
+ * that, so one is reported on the console rather than silently mangled.
+ *
+ * Shares `pf-option` with `pf-select` and `pf-combobox` through the generic
+ * `--pf-option-*` set.
+ *
+ * @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 chip - each chosen value's chip in the trigger.
+ * @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 PfMultiSelect {
+    el;
+    internals;
+    /** Submitted under this name, once per chosen value. Reflected. */
+    name;
+    /** The chosen values, comma-separated. Reflected, so HTML can set it. */
+    value = '';
+    /** Whether the listbox is showing. Reflected for the stylesheet. */
+    open = false;
+    label;
+    description;
+    error;
+    placeholder = 'Select options';
+    required = false;
+    disabled = false;
+    /** Options to show before the listbox scrolls. */
+    maxVisibleOptions;
+    /** Fires when the chosen set changes, with both representations. */
+    pfChange;
+    /** Fires whenever the listbox opens or closes, whoever caused it. */
+    pfOpenChange;
+    /** The labels of the chosen options, for the trigger's chips. */
+    chips = [];
+    initialValue = '';
+    stopObserving;
+    activeOption = null;
+    warnedAboutSeparator = false;
+    componentWillLoad() {
+        this.initialValue = this.value ?? '';
+        this.syncFormState();
+        this.syncOptions();
+    }
+    componentDidRender() {
+        this.syncActiveDescendant();
+    }
+    disconnectedCallback() {
+        this.stopObserving?.();
+    }
+    /*
+     * `name` is watched here and not on the controls that pass a plain string to
+     * `setFormValue`: those take their submission name from the reflected
+     * attribute, so the platform picks a change up by itself. This one builds
+     * the name *into* a FormData, so without the watch a name assigned after
+     * load would never reach the submission.
+     */
+    syncFormState() {
+        const values = this.values();
+        if (values.length === 0 || !this.name) {
+            this.internals.setFormValue(null);
+        }
+        else {
+            // One entry per value under the one name, which `data.getAll(name)`
+            // reads back as an array.
+            const data = new FormData();
+            for (const value of values)
+                data.append(this.name, value);
+            this.internals.setFormValue(data);
+        }
+        applyControlValidity(this.internals, values.length > 0, this.required, this.error);
+    }
+    /** The value changed, so the children's `selected` and the chips follow. */
+    syncOptions() {
+        const chosen = this.values();
+        const labels = [];
+        for (const option of this.options()) {
+            const selected = chosen.includes(this.optionValue(option));
+            option.selected = selected;
+        }
+        // Chips in the order they were chosen, not the options' order.
+        for (const value of chosen) {
+            const option = this.options().find((candidate) => this.optionValue(candidate) === value);
+            if (option)
+                labels.push(option.textContent?.trim() ?? value);
+        }
+        this.chips = labels;
+        this.warnAboutSeparators();
+    }
+    /**
+     * One warning naming every offending value.
+     *
+     * A value holding a comma cannot round-trip through `value`, and failing
+     * silently would show the right chips over a wrong submission.
+     */
+    warnAboutSeparators() {
+        if (this.warnedAboutSeparator)
+            return;
+        const offenders = assertSeparableValues(this.options().map((o) => this.optionValue(o)));
+        if (offenders.length === 0)
+            return;
+        this.warnedAboutSeparator = true;
+        console.warn(`[pf-multi-select] option values cannot contain a comma, because \`value\` is a ` +
+            `comma-separated list: ${offenders.join(' ')}`);
+    }
+    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;
+    }
+    /** Re-reads the options, for a label edited in place. */
+    async refresh() {
+        this.syncOptions();
+    }
+    onSlotChange = () => {
+        this.syncOptions();
+    };
+    values() {
+        return parseValueList(this.value);
+    }
+    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,
+            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`;
+            },
+        });
+        // Opens on the first chosen option, or the first selectable one.
+        const chosen = this.values();
+        const first = this.options().find((option) => chosen.includes(this.optionValue(option)) && !option.hasAttribute('disabled')) ?? this.enabled()[0];
+        this.setActive(first ?? null);
+    }
+    hideListbox() {
+        this.stopObserving?.();
+        this.stopObserving = undefined;
+        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' });
+        }
+    }
+    /** An element, not an IDREF: a cross-root IDREF resolves to nothing. */
+    syncActiveDescendant() {
+        const trigger = this.trigger;
+        if (!trigger || !('ariaActiveDescendantElement' in trigger))
+            return;
+        trigger.ariaActiveDescendantElement = this.open ? this.activeOption : null;
+    }
+    /**
+     * Toggles one value and keeps the listbox open — the difference from
+     * `pf-select`, and the whole point of a multi-choice control: closing after
+     * each pick would make choosing three things three round trips.
+     */
+    toggle(option) {
+        if (option.hasAttribute('disabled') || this.disabled)
+            return;
+        const next = toggleValueInList(this.values(), this.optionValue(option));
+        this.value = formatValueList(next);
+        this.pfChange.emit({ value: this.value, values: next });
+    }
+    handleOptionSelect(event) {
+        event.stopPropagation();
+        const option = this.options().find((candidate) => this.optionValue(candidate) === event.detail.value);
+        if (option)
+            this.toggle(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);
+    }
+    handleKeyDown(event) {
+        if (this.disabled || event.defaultPrevented)
+            return;
+        const move = MOVES[event.key];
+        if (move) {
+            event.preventDefault();
+            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.toggle(this.activeOption);
+        }
+    }
+    render() {
+        const describedBy = composeDescribedBy(this.description && 'description', this.error && 'error');
+        return (h(Host, { key: '68ee3f2e23741c14f955523bf3cbcb10e4fc3e71' }, h("div", { key: 'ffbfe398e848a5134740908327bca92afe74f39c', class: "field", part: "field" }, this.label && (h("label", { key: '7fe73bdad7836709b5e30536412283edf72abd37', class: "label", part: "label", htmlFor: "trigger" }, this.label, this.required && (h("span", { key: '1cecfe1256d01e6770417b030a8aba22ca65f802', class: "required", "aria-hidden": "true" }, "*")))), h("button", { key: '03c611dff79a67cda5478d586eaa301fd4178843', id: "trigger", 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;
+            } }, this.chips.length > 0 ? (h("span", { class: "chips" }, this.chips.map((chip) => (h("span", { key: chip, class: "chip", part: "chip" }, chip))))) : (h("span", { class: "placeholder" }, this.placeholder)), h("span", { key: 'a31710bfb23f890b33a010962b93792424b71e36', class: "chevron", "aria-hidden": "true" }, h("pf-icon", { key: '517857c8ab460c5a60a50d42c3ff68d986e0c744', name: "chevron-down" }))), this.description && (h("p", { key: '549f06c9be1d291d4654ac63c6f03f749453113d', class: "description", part: "description", id: "description" }, this.description)), this.error && (h("p", { key: '0da14622c434e02f6098a61382b22ee2b74a3f84', class: "error", part: "error", id: "error" }, this.error))), h("div", { key: 'f62c24c5870b4a05bcba73969af4721ed52bf4e3', id: "listbox", part: "listbox", class: "listbox", popover: "auto", role: "listbox", "aria-multiselectable": "true", "aria-label": this.label ?? this.placeholder, style: this.maxVisibleOptions
+                ? { maxHeight: `calc(${this.maxVisibleOptions} * 36px)`, overflowY: 'auto' }
+                : undefined, onToggle: this.onToggle }, h("slot", { key: '6d8c84b2173904d99f7b3583cbb2203636cd6214', onSlotchange: this.onSlotChange }))));
+    }
+    static get is() { return "pf-multi-select"; }
+    static get encapsulation() { return "shadow"; }
+    static get formAssociated() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["pf-multi-select.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["pf-multi-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, once per chosen value. Reflected."
+                },
+                "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 values, comma-separated. Reflected, so HTML can set it."
+                },
+                "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 options'"
+            },
+            "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."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max-visible-options"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "chips": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "pfChange",
+                "name": "pfChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fires when the chosen set changes, with both representations."
+                },
+                "complexType": {
+                    "original": "{ value: string; values: string[] }",
+                    "resolved": "{ value: string; values: 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.",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "name",
+                "methodName": "syncFormState"
+            }, {
+                "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-multi-select.js.map