@pine-ds/core 5.0.0-mercury.0 → 5.0.0

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

@@ -0,0 +1,728 @@
+import { Host, h } from "@stencil/core";
+import { HostStylingKeeper } from "../../utils/attributes";
+import { assignDescription, isSpecTest, messageId, exposeTypeProperty } from "../../utils/form";
+import { danger, enlarge } from "@pine-ds/icons/icons";
+/** The tags of an option list in order, optgroup contents included: equal shapes can be patched in place. */
+const shapeOf = (items) => items.map((item) => item.tagName + (item.tagName === 'OPTGROUP' ? `(${shapeOf(Array.from(item.children))})` : '')).join();
+/** Brings an existing option or optgroup up to date with its copy, keeping the element itself. */
+const patchInPlace = (target, copy) => {
+    Array.from(target.attributes).forEach(({ name }) => {
+        if (!copy.hasAttribute(name))
+            target.removeAttribute(name);
+    });
+    Array.from(copy.attributes).forEach(({ name, value }) => {
+        if (target.getAttribute(name) !== value)
+            target.setAttribute(name, value);
+    });
+    if (copy.tagName === 'OPTGROUP') {
+        Array.from(copy.children).forEach((child, index) => patchInPlace(target.children[index], child));
+    }
+    else if (target.textContent !== copy.textContent) {
+        target.textContent = copy.textContent;
+    }
+};
+/**
+ * @slot (default) - The `option` and `optgroup` elements to choose from. Other elements are ignored.
+ * @slot action - Content to be displayed in the label area, typically for help icons or links
+ * @part action - Exposes the wrapper around the `action` slot for styling. Appears only when the `action` slot has content.
+ * @part select - Exposes the native `select` element for styling.
+ */
+export class PdsSelect {
+    constructor() {
+        this._type = 'select-one';
+        this.optionObserver = null;
+        this.optionSyncFrame = null;
+        this.hasHadOptions = false;
+        this.hostKeeper = new HostStylingKeeper();
+        /**
+         * Indicates whether or not the select field is disabled.
+         * @defaultValue false
+         */
+        this.disabled = false;
+        /**
+         * Indicates whether multiple options can be selected.
+         * @defaultValue false
+         */
+        this.multiple = false;
+        /**
+         * Indicates whether or not the select field is required.
+         * @defaultValue false
+         */
+        this.required = false;
+        /**
+         * Whether a mutation is inside an option or optgroup. The host's own attributes and children
+         * (top-level adds and removes reach `slotchange`) and the action slot's content are not.
+         */
+        this.touchesOption = ({ target }) => {
+            // Not just TEXT_NODE: characterData also reports comment nodes, and a Comment has no
+            // .closest() — treating anything non-Element as a Text node crashed on one.
+            const element = target.nodeType === Node.ELEMENT_NODE ? target : target.parentElement;
+            return target !== this.el && (element === null || element === void 0 ? void 0 : element.closest('option, optgroup')) != null;
+        };
+        /**
+         * Emits an event on input change.
+        */
+        this.onSelectUpdate = (e) => {
+            const target = e.target;
+            const values = Array.from(target.options)
+                .filter((option) => (option.selected))
+                .map((option) => (option.value));
+            if (values.length === 1 && !this.multiple) {
+                this.value = values[0];
+            }
+            else {
+                this.value = values;
+            }
+            this.pdsSelectChange.emit(e);
+        };
+        this.onBlur = (ev) => {
+            this.pdsBlur.emit(ev);
+        };
+        this.onFocus = (ev) => {
+            this.pdsFocus.emit(ev);
+        };
+        this.onKeyDown = (ev) => {
+            this.pdsKeyDown.emit(ev);
+        };
+        /**
+         * Copies the slotted <option> and <optgroup> elements into the inner select, then
+         * reselects the current value. Runs on `slotchange` and when a slotted option changes
+         * (see startOptionSync).
+         *
+         * Nothing happens when the copies match what the select already holds. When only text or
+         * attributes changed, the select's own options are updated in place rather than replaced,
+         * so an open picker keeps its highlight, a multiple select keeps its range anchor, and a
+         * screen reader keeps its place. Selecting programmatically fires no change event, so a
+         * copy never emits `pdsSelectChange`.
+         */
+        this.handleSlotChange = () => {
+            var _a;
+            const slot = (_a = this.slotContainer) === null || _a === void 0 ? void 0 : _a.querySelector('slot');
+            if (slot === null || slot === undefined || this.selectEl === undefined)
+                return;
+            const copies = slot.assignedElements({ flatten: true })
+                .filter((item) => ['OPTION', 'OPTGROUP'].includes(item.tagName))
+                .map((item) => item.cloneNode(true));
+            const current = Array.from(this.selectEl.children);
+            // The very first copy populates an empty select, where falling back to the first option (like
+            // a native select) is correct; the no-match blank state is for options changing under a value
+            // that was already showing selected. Tracked separately from the select's current emptiness:
+            // an async reload that clears options before the next set lands would otherwise look like a
+            // first render again, and the no-match state must still apply once that next set arrives.
+            const hadOptions = this.hasHadOptions;
+            if (copies.length > 0)
+                this.hasHadOptions = true;
+            const markup = (items) => items.map((item) => item.outerHTML).join('');
+            if (markup(copies) === markup(current))
+                return;
+            if (shapeOf(copies) === shapeOf(current)) {
+                copies.forEach((copy, index) => patchInPlace(current[index], copy));
+            }
+            else {
+                this.selectEl.innerHTML = '';
+                copies.forEach((copy) => this.selectEl.appendChild(copy));
+            }
+            this.updateSelectedOption();
+            if (hadOptions)
+                this.showNoSelectionWithoutMatch();
+            this.updateFormValue();
+        };
+    }
+    /**
+     * Handles the change in the value of the select component.
+     * This method is called whenever the value of the select component changes.
+     * It updates the selected option accordingly.
+     */
+    valueChanged() {
+        this.updateSelectedOption();
+        this.updateFormValue();
+    }
+    /**
+     * Updates the type property when multiple changes to match native select behavior.
+     */
+    multipleChanged() {
+        this.updateType();
+    }
+    updateType() {
+        this._type = this.multiple ? 'select-multiple' : 'select-one';
+    }
+    connectedCallback() {
+        this.hostKeeper.connect(this.el);
+        // Initialize ElementInternals for form association (only once per element instance)
+        if (this.el.attachInternals && !this.internals) {
+            this.internals = this.el.attachInternals();
+        }
+        // Expose type property on the element instance to match native form element behavior
+        exposeTypeProperty(this.el, () => this._type);
+        // Reconnected after a move: componentDidLoad won't run again, and options may have changed
+        // while it was out of the document.
+        if (this.selectEl !== undefined) {
+            this.startOptionSync();
+            this.scheduleOptionSync();
+        }
+    }
+    disconnectedCallback() {
+        this.hostKeeper.disconnect();
+        this.stopOptionSync();
+    }
+    componentWillLoad() {
+        // Set initial type based on multiple prop
+        this.updateType();
+        this.updateSelectedOption();
+    }
+    componentDidLoad() {
+        // Set initial form value
+        this.updateFormValue();
+        // Stencil holds componentDidLoad until the shadow root's pds-icon has loaded, so options can
+        // change between the first slotchange copy and here with nothing observing yet — the same gap
+        // the reconnect path closes with a catch-up sync.
+        this.startOptionSync();
+        this.scheduleOptionSync();
+    }
+    /**
+     * Keeps the inner select in step with the slotted options. `slotchange` only fires when
+     * top-level options are added or removed, so an option's text, value or disabled state
+     * changing, or an option added inside an optgroup, would otherwise never reach the select.
+     * Changes are batched into one copy per animation frame.
+     */
+    startOptionSync() {
+        if (this.optionObserver !== null || typeof MutationObserver === 'undefined' || !this.el.isConnected)
+            return;
+        this.optionObserver = new MutationObserver((mutations) => {
+            if (mutations.some(this.touchesOption))
+                this.scheduleOptionSync();
+        });
+        this.optionObserver.observe(this.el, { childList: true, subtree: true, attributes: true, characterData: true });
+    }
+    scheduleOptionSync() {
+        if (this.optionSyncFrame !== null)
+            return;
+        this.optionSyncFrame = requestAnimationFrame(() => {
+            this.optionSyncFrame = null;
+            this.handleSlotChange();
+        });
+    }
+    stopOptionSync() {
+        var _a;
+        (_a = this.optionObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
+        this.optionObserver = null;
+        if (this.optionSyncFrame !== null) {
+            cancelAnimationFrame(this.optionSyncFrame);
+            this.optionSyncFrame = null;
+        }
+    }
+    /**
+     * Updates the selected option in the select element based on the current value.
+     *
+     * This method iterates through all the options of the select element and sets the
+     * 'selected' attribute on the option that matches the current value. If an option
+     * does not match the current value, the 'selected' attribute is removed.
+     *
+     * @private
+     * @returns {void}
+     */
+    updateSelectedOption() {
+        if (this.selectEl) {
+            const options = this.selectEl.options;
+            // Update the selected attribute for all options.
+            Array.from(options).map((option) => {
+                if (Array.isArray(this.value)) {
+                    option.selected = this.value.includes(option.value);
+                }
+                else {
+                    option.selected = this.value === option.value;
+                }
+            });
+        }
+        ;
+    }
+    /**
+     * After a copy that changes an existing option set, a value whose option was renamed or removed
+     * has nothing to select. Like a native select, show nothing selected rather than the first
+     * option; the value itself is kept, with no change event.
+     */
+    showNoSelectionWithoutMatch() {
+        var _a;
+        const wanted = [].concat((_a = this.value) !== null && _a !== void 0 ? _a : []).filter((value) => value !== '');
+        const options = Array.from(this.selectEl.options);
+        if (wanted.length > 0 && !options.some((option) => wanted.includes(option.value))) {
+            this.selectEl.selectedIndex = -1;
+        }
+    }
+    getHelperMessage() {
+        return this.helperMessage && (h("p", { class: "pds-select__helper-message", id: messageId(this.componentId, 'helper') }, this.helperMessage));
+    }
+    getErrorMessage() {
+        return this.errorMessage && (h("p", { class: "pds-select__error-message", id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { "aria-hidden": "true", icon: danger, size: "small" }), this.errorMessage));
+    }
+    renderMessages() {
+        if (!this.helperMessage && !this.errorMessage)
+            return null;
+        return (h("div", { class: "pds-select__message" }, this.getHelperMessage(), this.getErrorMessage()));
+    }
+    // The field also renders as invalid whenever an error message is present, via
+    // `select:has(~ .pds-select__message .pds-select__error-message)` in the styles.
+    isInvalid() {
+        return Boolean(this.invalid) || Boolean(this.errorMessage);
+    }
+    classNames() {
+        const classNames = [];
+        if (this.invalid) {
+            classNames.push('is-invalid');
+        }
+        if (this.disabled) {
+            classNames.push('is-disabled');
+        }
+        return classNames.join('  ');
+    }
+    renderAction() {
+        const hasAction = this.el.querySelector('[slot="action"]') !== null;
+        if (hasAction) {
+            return (h("div", { class: "pds-select__action", part: "action" }, h("slot", { name: "action" })));
+        }
+        return null;
+    }
+    /**
+     * Updates the form value using ElementInternals API
+     */
+    updateFormValue() {
+        if (isSpecTest())
+            return;
+        if (this.internals && this.internals.setFormValue) {
+            const value = this.value;
+            // Handle multi-select arrays by converting to FormData or comma-separated string
+            if (Array.isArray(value)) {
+                if (value.length > 1) {
+                    // For multiple values, create FormData with multiple entries
+                    const formData = new FormData();
+                    value.forEach(val => formData.append(this.name || '', val));
+                    this.internals.setFormValue(formData);
+                }
+                else {
+                    // Single value in array, use the string value
+                    this.internals.setFormValue(value[0] || null);
+                }
+            }
+            else {
+                // Single string value
+                this.internals.setFormValue(value || null);
+            }
+            // Set validity based on native select validation
+            if (this.selectEl && this.internals && this.internals.setValidity) {
+                this.internals.setValidity(this.selectEl.validity, this.selectEl.validationMessage, this.selectEl);
+            }
+        }
+    }
+    /**
+     * Form Associated Custom Elements API: Called when the form is reset
+     */
+    formResetCallback() {
+        this.value = '';
+        this.updateFormValue();
+    }
+    /**
+     * Form Associated Custom Elements API: Called when the form is disabled
+     */
+    formDisabledCallback(disabled) {
+        this.disabled = disabled;
+    }
+    /**
+     * Form Associated Custom Elements API: Called to restore form state
+     */
+    formStateRestoreCallback(state) {
+        if (typeof state === 'string') {
+            this.value = state;
+        }
+        else if (state instanceof FormData && this.name) {
+            // Extract value(s) from FormData using the select's name
+            const values = state.getAll(this.name);
+            if (values.length > 1) {
+                // Multi-select: convert to string array
+                this.value = values.filter(v => typeof v === 'string');
+            }
+            else if (values.length === 1 && typeof values[0] === 'string') {
+                // Single select: use string value
+                this.value = values[0];
+            }
+        }
+    }
+    render() {
+        const hasAction = this.el.querySelector('[slot="action"]') !== null;
+        const hostClass = this.classNames();
+        const hostAttributes = {
+            'aria-disabled': this.disabled ? 'true' : null,
+            'has-action': hasAction && !this.hideLabel ? 'true' : null,
+        };
+        this.hostKeeper.record(hostClass, {}, hostAttributes);
+        return (h(Host, Object.assign({ key: '6ffb35c5166a0759fbe7b3daa0b674c5f10458fa', class: hostClass }, hostAttributes), h("div", { key: '1e2d73b3a65189c29a34c1ce4473cce190f052c0', class: "pds-select" }, !this.hideLabel && (h("div", { key: '467c75d7232e4667975419a0dcad28231ca240a1', class: "pds-select__label-wrapper" }, h("label", { key: '9dd08c5c71a23c762f9d38fcec525a05ced7d48b', htmlFor: this.componentId }, h("span", { key: '94e5f054aa6e75e458f24c02ba9a6cda81f112d7', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), hasAction && this.renderAction())), h("select", { key: '18c626e10851041042ab4d6dfe700d49a9b3312b', "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-label": this.hideLabel ? this.label : undefined, autocomplete: this.autocomplete || undefined, class: "pds-select__field", disabled: this.disabled, id: this.componentId, multiple: this.multiple, name: this.name, onBlur: this.onBlur, onChange: this.onSelectUpdate, onFocus: this.onFocus, onKeyDown: this.onKeyDown, part: "select", required: this.required, ref: (el) => (this.selectEl = el) }), h("div", { key: '08c6cee6b009d22b0ed70cc8231d3c2c8637099d', "aria-hidden": "true", class: "hidden", ref: (el) => (this.slotContainer = el) }, h("slot", { key: '2ebcb906f8816e3bf26d5e4f82f8ea2d9ca2256a', onSlotchange: this.handleSlotChange })), this.renderMessages(), !this.multiple && h("pds-icon", { key: '191f489efb78fc7066fc0b5a1f5da1f7cda446e8', "aria-hidden": "true", class: "pds-select__select-icon", icon: enlarge }))));
+    }
+    static get is() { return "pds-select"; }
+    static get encapsulation() { return "shadow"; }
+    static get formAssociated() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["pds-select.tokens.scss", "../../global/styles/utils/label.scss", "pds-select.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["pds-select.tokens.css", "../../global/styles/utils/label.css", "pds-select.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "autocomplete": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Specifies if and how the browser provides `autocomplete` assistance for the field."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "autocomplete"
+            },
+            "componentId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "A unique identifier used for the underlying component `id` attribute."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "component-id"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "false"
+                        }],
+                    "text": "Indicates whether or not the select field is disabled."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "errorMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Displays an error message below the select and marks the select as invalid, with or without `invalid`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "error-message"
+            },
+            "hideLabel": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Visually hides the label text for instances where only the select should be displayed. Label remains accessible to assistive technology such as screen readers.\nNote: When true, the action slot is also hidden to maintain a minimal UI."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "hide-label"
+            },
+            "helperMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Displays a message or hint below the select."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "helper-message"
+            },
+            "invalid": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Determines whether or not the select is invalid."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "invalid"
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Text to be displayed as the select label."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label"
+            },
+            "multiple": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "false"
+                        }],
+                    "text": "Indicates whether multiple options can be selected."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "multiple",
+                "defaultValue": "false"
+            },
+            "name": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Specifies the name. Submitted with the form name/value pair."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "name"
+            },
+            "required": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "false"
+                        }],
+                    "text": "Indicates whether or not the select field is required."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "required",
+                "defaultValue": "false"
+            },
+            "highlight": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Applies highlight styling to the select field."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "highlight"
+            },
+            "value": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string | string[]",
+                    "resolved": "string | string[]",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "The value(s) of the selected option(s)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "value"
+            }
+        };
+    }
+    static get events() {
+        return [{
+                "method": "pdsSelectChange",
+                "name": "pdsSelectChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when the user changes the selection. `detail` is the native `change` event, so read the new value\nfrom the select's `value`: a string, or an array with `multiple`.\n\nThis event will not emit when programmatically setting the `value` property."
+                },
+                "complexType": {
+                    "original": "InputEvent",
+                    "resolved": "InputEvent",
+                    "references": {
+                        "InputEvent": {
+                            "location": "global",
+                            "id": "global::InputEvent"
+                        }
+                    }
+                }
+            }, {
+                "method": "pdsBlur",
+                "name": "pdsBlur",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when the select loses focus."
+                },
+                "complexType": {
+                    "original": "FocusEvent",
+                    "resolved": "FocusEvent",
+                    "references": {
+                        "FocusEvent": {
+                            "location": "global",
+                            "id": "global::FocusEvent"
+                        }
+                    }
+                }
+            }, {
+                "method": "pdsFocus",
+                "name": "pdsFocus",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when the select gains focus."
+                },
+                "complexType": {
+                    "original": "FocusEvent",
+                    "resolved": "FocusEvent",
+                    "references": {
+                        "FocusEvent": {
+                            "location": "global",
+                            "id": "global::FocusEvent"
+                        }
+                    }
+                }
+            }, {
+                "method": "pdsKeyDown",
+                "name": "pdsKeyDown",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when a key is pressed down in the select."
+                },
+                "complexType": {
+                    "original": "KeyboardEvent",
+                    "resolved": "KeyboardEvent",
+                    "references": {
+                        "KeyboardEvent": {
+                            "location": "global",
+                            "id": "global::KeyboardEvent"
+                        }
+                    }
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "value",
+                "methodName": "valueChanged"
+            }, {
+                "propName": "multiple",
+                "methodName": "multipleChanged"
+            }];
+    }
+}