@nova-design-system/nova-webcomponents 3.5.0 → 3.7.0

package/dist/collection/components/nv-fieldmultiselect/nv-fieldmultiselect.js

@@ -27,6 +27,11 @@ export class NvFieldmultiselect {
          * always type in fresh data.
          */
         this.autocomplete = 'off';
+        /**
+         * Specifies the selected values of the multiselect field.
+         * This is the canonical value for the component and is used for form submission.
+         */
+        this.value = [];
         /**
          * Marks the input field as required.
          */
@@ -80,17 +85,13 @@ export class NvFieldmultiselect {
          * Text for the badge showing the number of selected items.
          */
         this.badgeLabel = '';
-        //#endregion PROPERTIES
-        /****************************************************************************/
-        //#region STATE
         /**
          * The text entered by the user for filtering multiselect items.
          */
         this.filterText = '';
-        /**
-         * List of selected values in the multiselect.
-         */
-        this.selectedValues = [];
+        //#endregion PROPERTIES
+        /****************************************************************************/
+        //#region STATE
         /**
          * Sorted options for display.
          */
@@ -100,8 +101,8 @@ export class NvFieldmultiselect {
          * Handle badge close for options mode.
          */
         this.handleBadgeCloseOptions = () => {
-            this.selectedValues = [];
-            this.multiselectChange.emit(this.selectedValues);
+            this.value = [];
+            this.valueChanged.emit(this.value);
             // Uncheck all elements
             const items = Array.from(this.el.querySelectorAll('nv-fielddropdownitemcheck'));
             items.forEach(item => {
@@ -117,8 +118,8 @@ export class NvFieldmultiselect {
          * Handle badge close for slots mode.
          */
         this.handleBadgeCloseSlots = () => {
-            this.selectedValues = [];
-            this.multiselectChange.emit(this.selectedValues);
+            this.value = [];
+            this.valueChanged.emit(this.value);
             // Uncheck all elements
             const items = Array.from(this.el.querySelectorAll('nv-fielddropdownitemcheck'));
             items.forEach(item => {
@@ -136,12 +137,19 @@ export class NvFieldmultiselect {
             if (this.isHandlingEscape) {
                 return;
             }
-            this.filterText = '';
-            // Reset filter if needed
+            // Reset filter if needed, but preserve the filter text
             if (this.filterable) {
                 this.resetFilter();
             }
         };
+        /**
+         * Clear the filter text
+         */
+        this.clearFilterText = () => {
+            this.filterText = '';
+            this.filterTextChanged.emit('');
+            this.resetFilter();
+        };
         /**
          * Handle input blur for options mode.
          */
@@ -150,10 +158,9 @@ export class NvFieldmultiselect {
                 if (!this.el.contains(document.activeElement)) {
                     // Close the popover without affecting the divider
                     this.open = false;
-                    // Reset filter if needed
+                    // Clear filter text when focus is lost
                     if (this.filterable) {
-                        this.filterText = '';
-                        this.resetFilter();
+                        this.clearFilterText();
                     }
                 }
             }, 150);
@@ -211,15 +218,14 @@ export class NvFieldmultiselect {
                 return;
             }
             const input = event.target;
-            this.value = input.value;
-            this.valueChanged.emit(this.value);
+            this.filterText = input.value;
+            this.filterTextChanged.emit(this.filterText);
             // Clear any existing timer
             if (this.debounceTimer) {
                 window.clearTimeout(this.debounceTimer);
             }
             // Set a new timer for filtering
             this.debounceTimer = window.setTimeout(() => {
-                this.filterText = input.value.toLowerCase();
                 this.filterItemsOption();
             }, this.debounceDelay);
         };
@@ -233,15 +239,14 @@ export class NvFieldmultiselect {
             if (this.disabled || this.readonly)
                 return;
             const input = event.target;
-            this.value = input.value;
-            this.valueChanged.emit(this.value);
+            this.filterText = input.value;
+            this.filterTextChanged.emit(this.filterText);
             // Clear any existing timer
             if (this.debounceTimer) {
                 window.clearTimeout(this.debounceTimer);
             }
             // Set a new timer for filtering
             this.debounceTimer = window.setTimeout(() => {
-                this.filterText = input.value.toLowerCase();
                 this.filterSlotsItems();
             }, this.debounceDelay);
         };
@@ -271,10 +276,9 @@ export class NvFieldmultiselect {
                 if (!this.el.contains(document.activeElement)) {
                     // Close the popover without affecting the divider
                     this.open = false;
-                    // Reset filter if needed
+                    // Clear filter text when focus is lost
                     if (this.filterable) {
-                        this.filterText = '';
-                        this.resetFilter();
+                        this.clearFilterText();
                     }
                 }
             }, 150);
@@ -305,14 +309,14 @@ export class NvFieldmultiselect {
          * @returns {any} The JSX for options mode
          */
         this.renderOptionsMode = () => {
-            return (h(Host, { "aria-label": this.label, "aria-expanded": this.open.toString() }, (this.label || this.el.querySelector('[slot="label"]')) && (h("label", { htmlFor: this.inputId }, h("slot", { name: "label" }, this.label))), h("nv-popover", { ref: el => (this.popoverElement = el), triggerMode: "controlled", placement: "bottom-start", open: this.open }, h("div", { class: "input-wrapper-multiselect", slot: "trigger" }, h("slot", { name: "before-input" }), h("div", { class: "input-container-multiselect" }, h("slot", { name: "leading-input" }), this.selectedValues.length > 0 && (h("nv-badge", { slot: "leading-input", "prevent-auto-close": true, color: "10", dismissible: this.selectedValues.length > 0, label: `${this.selectedValues.length} ${this.badgeLabel}`, "aria-label": `Clear all ${this.selectedValues.length} ${this.badgeLabel} items`, onCloseClicked: this.handleBadgeCloseOptions })), this.filterable || this.disabled || this.readonly ? (h("input", { type: "text", id: this.inputId, ref: e => (this.inputElement = e), autofocus: this.autofocus, autocomplete: this.autocomplete, placeholder: this.placeholder, name: this.name, value: this.value, required: this.required, disabled: this.disabled, readOnly: this.readonly, onInput: this.handleInputOptions, onFocus: this.handleInputFocusOptions, onBlur: this.handleInputBlurOptions, onKeyDown: this.handleKeyDown, "data-scope": "focusable" })) : (h("p", { id: this.inputId, class: "non-filterable-text", onClick: this.handleInputContainerClickOptions, tabIndex: 0, onKeyDown: this.handleKeyDown, onFocus: this.handleInputFocusOptions, role: "combobox", "aria-expanded": this.open, "data-scope": "focusable" }, h("span", null, this.value || this.placeholder))), this.error && (h("nv-icon", { name: "alert-circle", class: "validation", size: "md" })), h("nv-iconbutton", { "data-scope": "toggle-dropdown", name: this.open ? 'chevron-top' : 'chevron-down', size: "md", emphasis: "lower", "aria-label": this.open ? 'Hide dropdown' : 'Show dropdown', "aria-pressed": this.open.toString(), onClick: this.togglePopoverOptions })), h("slot", { name: "after-input" })), h("div", { slot: "content", role: "listbox", "aria-multiselectable": "true", style: this.maxHeight ? { maxHeight: this.maxHeight } : {} }, h("ul", { role: "content" }, this.options.map(option => (h("nv-fielddropdownitemcheck", { label: option.label, description: option.description, value: option.value, checked: this.selectedValues.includes(option.value), disabled: option.disabled }))), h("hr", { class: "multiselect-divider", style: { display: 'none' } })))), this.renderDescriptions()));
+            return (h(Host, { "aria-label": this.label, "aria-expanded": this.open.toString() }, (this.label || this.el.querySelector('[slot="label"]')) && (h("label", { htmlFor: this.inputId }, h("slot", { name: "label" }, this.label))), h("nv-popover", { ref: el => (this.popoverElement = el), triggerMode: "controlled", placement: "bottom-start", open: this.open }, h("div", { class: "input-wrapper-multiselect", slot: "trigger" }, h("slot", { name: "before-input" }), h("div", { class: "input-container-multiselect" }, h("slot", { name: "leading-input" }), this.value.length > 0 && (h("nv-badge", { slot: "leading-input", "prevent-auto-close": true, color: "10", dismissible: this.value.length > 0, label: `${this.value.length} ${this.badgeLabel}`, "aria-label": `Clear all ${this.value.length} ${this.badgeLabel} items`, onCloseClicked: this.handleBadgeCloseOptions })), this.filterable || this.disabled || this.readonly ? (h("input", { type: "text", id: this.inputId, ref: e => (this.inputElement = e), autofocus: this.autofocus, autocomplete: this.autocomplete, placeholder: this.placeholder, name: this.name, value: this.filterText, required: this.required, disabled: this.disabled, readOnly: this.readonly, onInput: this.handleInputOptions, onFocus: this.handleInputFocusOptions, onBlur: this.handleInputBlurOptions, onKeyDown: this.handleKeyDown, "data-scope": "focusable" })) : (h("p", { id: this.inputId, class: "non-filterable-text", onClick: this.handleInputContainerClickOptions, tabIndex: 0, onKeyDown: this.handleKeyDown, onFocus: this.handleInputFocusOptions, role: "combobox", "aria-expanded": this.open, "data-scope": "focusable" }, h("span", null, this.placeholder))), this.error && (h("nv-icon", { name: "alert-circle", class: "validation", size: "md" })), this.filterable && this.filterText.length > 0 && (h("nv-iconbutton", { "data-scope": "clear-filter", name: "x", size: "md", emphasis: "lower", tabindex: "-1", onClick: this.clearFilterText, "aria-label": "Clear filter text" })), h("nv-iconbutton", { "data-scope": "toggle-dropdown", name: this.open ? 'chevron-top' : 'chevron-down', size: "md", emphasis: "lower", "aria-label": this.open ? 'Hide dropdown' : 'Show dropdown', "aria-pressed": this.open.toString(), onClick: this.togglePopoverOptions })), h("slot", { name: "after-input" })), h("div", { slot: "content", role: "listbox", "aria-multiselectable": "true", style: this.maxHeight ? { maxHeight: this.maxHeight } : {} }, h("ul", { role: "content" }, this.options.map(option => (h("nv-fielddropdownitemcheck", { label: option.label, description: option.description, value: option.value, checked: this.value.includes(option.value), disabled: option.disabled }))), h("hr", { class: "multiselect-divider", style: { display: 'none' } })))), this.renderDescriptions()));
         };
         /**
          * Renders the component in slots mode
          * @returns {any} The JSX for slots mode
          */
         this.renderSlotsMode = () => {
-            return (h(Host, { "aria-label": this.label, "aria-expanded": this.open.toString() }, (this.label || this.el.querySelector('[slot="label"]')) && (h("label", { htmlFor: this.inputId }, h("slot", { name: "label" }, this.label))), h("nv-popover", { ref: el => (this.popoverElement = el), triggerMode: "controlled", placement: "bottom-start", open: this.open }, h("div", { class: "input-wrapper-multiselect", slot: "trigger" }, h("slot", { name: "before-input" }), h("div", { class: "input-container-multiselect", onClick: this.handleInputContainerClickSlots }, h("slot", { name: "leading-input" }), this.selectedValues.length > 0 && (h("nv-badge", { slot: "leading-input", "prevent-auto-close": true, color: "10", dismissible: this.selectedValues.length > 0, label: `${this.selectedValues.length} ${this.badgeLabel}`, "aria-label": `Clear all ${this.selectedValues.length} ${this.badgeLabel} items`, onCloseClicked: this.handleBadgeCloseSlots })), this.filterable || this.disabled || this.readonly ? (h("input", { id: this.inputId, ref: e => (this.inputElement = e), autocomplete: this.autocomplete, placeholder: this.placeholder, name: this.name, value: this.value, required: this.required, disabled: this.disabled, readOnly: this.readonly, onInput: this.handleInputSlots, onFocus: this.handleInputFocusSlots, onBlur: this.handleInputBlurSlots, onKeyDown: this.handleKeyDown, "data-scope": "focusable" })) : (h("p", { id: this.inputId, class: "non-filterable-text", onClick: this.handleInputContainerClickSlots, tabIndex: 0, onKeyDown: this.handleKeyDown, onFocus: this.handleInputFocusSlots, role: "combobox", "aria-expanded": this.open, "data-scope": "focusable" }, h("span", null, this.value || this.placeholder))), this.error && (h("nv-icon", { name: "alert-circle", class: "validation", size: "md" })), h("nv-iconbutton", { "data-scope": "toggle-dropdown", name: this.open ? 'chevron-top' : 'chevron-down', size: "md", emphasis: "lower", "aria-label": this.open ? 'Hide dropdown' : 'Show dropdown', "aria-pressed": this.open.toString(), onClick: this.togglePopoverSlots })), h("slot", { name: "after-input" })), h("div", { slot: "content", role: "listbox", "aria-multiselectable": "true", style: this.maxHeight ? { maxHeight: this.maxHeight } : {} }, h("slot", { name: "content" }))), this.renderDescriptions()));
+            return (h(Host, { "aria-label": this.label, "aria-expanded": this.open.toString() }, (this.label || this.el.querySelector('[slot="label"]')) && (h("label", { htmlFor: this.inputId }, h("slot", { name: "label" }, this.label))), h("nv-popover", { ref: el => (this.popoverElement = el), triggerMode: "controlled", placement: "bottom-start", open: this.open }, h("div", { class: "input-wrapper-multiselect", slot: "trigger" }, h("slot", { name: "before-input" }), h("div", { class: "input-container-multiselect", onClick: this.handleInputContainerClickSlots }, h("slot", { name: "leading-input" }), this.value.length > 0 && (h("nv-badge", { slot: "leading-input", "prevent-auto-close": true, color: "10", dismissible: this.value.length > 0, label: `${this.value.length} ${this.badgeLabel}`, "aria-label": `Clear all ${this.value.length} ${this.badgeLabel} items`, onCloseClicked: this.handleBadgeCloseSlots })), this.filterable || this.disabled || this.readonly ? (h("input", { id: this.inputId, ref: e => (this.inputElement = e), autocomplete: this.autocomplete, placeholder: this.placeholder, name: this.name, value: this.filterText, required: this.required, disabled: this.disabled, readOnly: this.readonly, onInput: this.handleInputSlots, onFocus: this.handleInputFocusSlots, onBlur: this.handleInputBlurSlots, onKeyDown: this.handleKeyDown, "data-scope": "focusable" })) : (h("p", { id: this.inputId, class: "non-filterable-text", onClick: this.handleInputContainerClickSlots, tabIndex: 0, onKeyDown: this.handleKeyDown, onFocus: this.handleInputFocusSlots, role: "combobox", "aria-expanded": this.open, "data-scope": "focusable" }, h("span", null, this.placeholder))), this.error && (h("nv-icon", { name: "alert-circle", class: "validation", size: "md" })), this.filterable && this.filterText.length > 0 && (h("nv-iconbutton", { name: "x", size: "md", emphasis: "lower", tabindex: "-1", onClick: this.clearFilterText, "aria-label": "Clear filter text" })), h("nv-iconbutton", { "data-scope": "toggle-dropdown", name: this.open ? 'chevron-top' : 'chevron-down', size: "md", emphasis: "lower", "aria-label": this.open ? 'Hide dropdown' : 'Show dropdown', "aria-pressed": this.open.toString(), onClick: this.togglePopoverSlots })), h("slot", { name: "after-input" })), h("div", { slot: "content", role: "listbox", "aria-multiselectable": "true", style: this.maxHeight ? { maxHeight: this.maxHeight } : {} }, h("slot", { name: "content" }))), this.renderDescriptions()));
         };
     }
     //#endregion EVENTS
@@ -321,7 +325,7 @@ export class NvFieldmultiselect {
     handleOptionsChange(newValue) {
         if (!newValue)
             return;
-        this.selectedValues = newValue
+        this.value = newValue
             .filter(option => option.checked)
             .map(option => option.value);
         this.reorderOptionsContent();
@@ -330,8 +334,10 @@ export class NvFieldmultiselect {
      * Emitted when the value changes.
      */
     watchValueHandler() {
-        // Handle value change and update the corresponding multiselect item if it exists
-        this.setInitialSelection();
+        // Synchronize child components when value changes programmatically
+        if (this.el && this.el.isConnected) {
+            this.syncChildComponents();
+        }
     }
     //#endregion WATCHERS
     /****************************************************************************/
@@ -371,22 +377,23 @@ export class NvFieldmultiselect {
         }
         const { value, checked } = event.detail;
         if (value !== undefined && value !== null) {
-            const newSelectedValues = [...this.selectedValues];
-            const valueIndex = newSelectedValues.indexOf(value);
+            const newValue = [...this.value];
+            const valueIndex = newValue.indexOf(value);
             if (checked && valueIndex === -1) {
-                newSelectedValues.push(value);
+                newValue.push(value);
             }
             else if (!checked && valueIndex > -1) {
-                newSelectedValues.splice(valueIndex, 1);
+                newValue.splice(valueIndex, 1);
             }
-            // Update the state and emit the event only if the selection has changed
-            if (JSON.stringify(this.selectedValues) !==
-                JSON.stringify(newSelectedValues)) {
-                this.selectedValues = newSelectedValues;
-                // Use requestAnimationFrame to ensure the state is updated before emitting the event
-                requestAnimationFrame(() => {
-                    this.multiselectChange.emit(this.selectedValues);
-                });
+            // Always update the state and emit the event when an item is checked/unchecked
+            this.value = newValue;
+            this.valueChanged.emit(this.value);
+            // Update the checked state of all items to ensure consistency
+            this.syncChildComponents();
+            // Preserve the filter text in the input
+            if (this.filterable && this.inputElement) {
+                // Keep the current filter text in the input
+                this.inputElement.value = this.filterText;
             }
         }
         else {
@@ -425,12 +432,10 @@ export class NvFieldmultiselect {
         }
         // Specific initialization for slots mode
         if (!this.options) {
+            // Use a microtask to ensure DOM is ready
             Promise.resolve().then(() => {
-                const items = Array.from(this.el.querySelectorAll('nv-fielddropdownitemcheck'));
-                // Initialize selectedValues with checked items
-                this.selectedValues = items
-                    .filter(item => item.hasAttribute('checked'))
-                    .map(item => item.getAttribute('value') || '');
+                // Synchronize child components
+                this.syncChildComponents();
                 // Force a reorder after initialization
                 requestAnimationFrame(() => {
                     this.reorderSlotContent();
@@ -441,13 +446,8 @@ export class NvFieldmultiselect {
         if (this.options) {
             this.sortedOptions = [...((_a = this.options) !== null && _a !== void 0 ? _a : [])];
         }
-        // Apply filtering if the multiselect is filterable and there is a value
-        if (this.filterable && this.value) {
-            this.filterText = String(this.value).toLocaleLowerCase();
-            this.filterItems();
-        }
-        else {
-            // Reset visibility state of all dropdown items
+        // Reset filter if needed
+        if (!this.filterText) {
             this.resetFilter();
         }
     }
@@ -458,6 +458,8 @@ export class NvFieldmultiselect {
         if (this.options) {
             this.handleOptionsChange(this.options);
         }
+        // Final synchronization of child components after everything is loaded
+        this.syncChildComponents();
     }
     /**
      * Unsubscribe from click outside event.
@@ -475,38 +477,6 @@ export class NvFieldmultiselect {
     async getFilterText() {
         return this.filterText;
     }
-    /**
-     * Set the initial selection based on the current value and update the inputElement value.
-     */
-    setInitialSelection() {
-        var _a;
-        const items = Array.from(this.el.querySelectorAll('nv-fielddropdownitem'));
-        const selectedItem = items.find(item => {
-            var _a;
-            return item.getAttribute('label') === this.value ||
-                item.getAttribute('value') === this.value ||
-                ((_a = item.textContent) === null || _a === void 0 ? void 0 : _a.trim()) === this.value;
-        });
-        // Remove 'selected' from all items first to reset the state
-        items.forEach(item => {
-            item.removeAttribute('selected');
-            item.classList.remove('selected');
-        });
-        if (selectedItem) {
-            // Add the `selected` attribute and `selected` class for visual styling
-            selectedItem.setAttribute('selected', 'true');
-            selectedItem.classList.add('selected');
-            // Update the value and inputElement value to reflect the pre-selected item
-            this.value =
-                selectedItem.getAttribute('label') ||
-                    selectedItem.getAttribute('value') ||
-                    ((_a = selectedItem.textContent) === null || _a === void 0 ? void 0 : _a.trim()) ||
-                    '';
-            if (this.inputElement) {
-                this.inputElement.value = this.value;
-            }
-        }
-    }
     /**
      * Reset the filter and make all items visible.
      */
@@ -523,8 +493,8 @@ export class NvFieldmultiselect {
             if (emptyMessage)
                 emptyMessage.remove();
             // Reorder with divider if needed
-            const selectedItems = items.filter(item => this.selectedValues.includes(item.getAttribute('value') || ''));
-            const unselectedItems = items.filter(item => !this.selectedValues.includes(item.getAttribute('value') || ''));
+            const selectedItems = items.filter(item => this.value.includes(item.getAttribute('value') || ''));
+            const unselectedItems = items.filter(item => !this.value.includes(item.getAttribute('value') || ''));
             if (selectedItems.length > 0) {
                 this.manageDivider(ul, selectedItems, unselectedItems);
             }
@@ -535,7 +505,7 @@ export class NvFieldmultiselect {
      * @returns {string[]} The selected values.
      */
     async getSelectedValues() {
-        return this.selectedValues;
+        return this.value;
     }
     /**
      * Reorder the content of the slot.
@@ -557,8 +527,8 @@ export class NvFieldmultiselect {
             return;
         }
         // Separate checked vs unchecked
-        const selectedItems = items.filter(item => this.selectedValues.includes(item.getAttribute('value') || ''));
-        const unselectedItems = items.filter(item => !this.selectedValues.includes(item.getAttribute('value') || ''));
+        const selectedItems = items.filter(item => this.value.includes(item.getAttribute('value') || ''));
+        const unselectedItems = items.filter(item => !this.value.includes(item.getAttribute('value') || ''));
         // Reinsert CHECKED items FIRST
         // appendChild() moves the element without recreating it
         // this is not trigger a re-rendering of the component in the platforms
@@ -584,8 +554,8 @@ export class NvFieldmultiselect {
         if (!ul)
             return;
         const items = Array.from(ul.querySelectorAll('nv-fielddropdownitemcheck')).filter(item => item.style.display !== 'none');
-        const selectedItems = items.filter(item => this.selectedValues.includes(item.getAttribute('value') || ''));
-        const unselectedItems = items.filter(item => !this.selectedValues.includes(item.getAttribute('value') || ''));
+        const selectedItems = items.filter(item => this.value.includes(item.getAttribute('value') || ''));
+        const unselectedItems = items.filter(item => !this.value.includes(item.getAttribute('value') || ''));
         // Reorder the elements
         selectedItems.forEach(item => ul.appendChild(item));
         unselectedItems.forEach(item => ul.appendChild(item));
@@ -621,8 +591,8 @@ export class NvFieldmultiselect {
             }
             // Reorder with divider
             const items = Array.from(ul.querySelectorAll('nv-fielddropdownitemcheck'));
-            const selectedItems = items.filter(item => this.selectedValues.includes(item.getAttribute('value') || ''));
-            const unselectedItems = items.filter(item => !this.selectedValues.includes(item.getAttribute('value') || ''));
+            const selectedItems = items.filter(item => this.value.includes(item.getAttribute('value') || ''));
+            const unselectedItems = items.filter(item => !this.value.includes(item.getAttribute('value') || ''));
             this.manageDivider(ul, selectedItems, unselectedItems);
             return;
         }
@@ -643,8 +613,8 @@ export class NvFieldmultiselect {
             });
             // Manage the divider with the visible items
             const visibleItems = items.filter(item => item.style.display !== 'none');
-            const visibleSelected = visibleItems.filter(item => this.selectedValues.includes(item.getAttribute('value') || ''));
-            const visibleUnselected = visibleItems.filter(item => !this.selectedValues.includes(item.getAttribute('value') || ''));
+            const visibleSelected = visibleItems.filter(item => this.value.includes(item.getAttribute('value') || ''));
+            const visibleUnselected = visibleItems.filter(item => !this.value.includes(item.getAttribute('value') || ''));
             this.manageDivider(ul, visibleSelected, visibleUnselected);
         }
         else {
@@ -702,8 +672,8 @@ export class NvFieldmultiselect {
         });
         // Manage the divider with the visible items
         const visibleItems = items.filter(item => item.style.display !== 'none');
-        const visibleSelected = visibleItems.filter(item => this.selectedValues.includes(item.getAttribute('value') || ''));
-        const visibleUnselected = visibleItems.filter(item => !this.selectedValues.includes(item.getAttribute('value') || ''));
+        const visibleSelected = visibleItems.filter(item => this.value.includes(item.getAttribute('value') || ''));
+        const visibleUnselected = visibleItems.filter(item => !this.value.includes(item.getAttribute('value') || ''));
         this.manageDivider(ul, visibleSelected, visibleUnselected);
         // Add or remove the empty message based on the case
         if (!hasVisibleItems) {
@@ -751,8 +721,8 @@ export class NvFieldmultiselect {
         });
         // Get visible items after filtering
         const visibleItems = items.filter(item => item.style.display !== 'none');
-        const visibleSelectedItems = visibleItems.filter(item => this.selectedValues.includes(item.getAttribute('value') || ''));
-        this.manageDivider(ul, visibleSelectedItems, visibleItems.filter(item => !this.selectedValues.includes(item.getAttribute('value') || '')));
+        const visibleSelectedItems = visibleItems.filter(item => this.value.includes(item.getAttribute('value') || ''));
+        this.manageDivider(ul, visibleSelectedItems, visibleItems.filter(item => !this.value.includes(item.getAttribute('value') || '')));
         // Add empty message if no items match the filter
         if (!hasVisibleItems) {
             const emptyMessage = document.createElement('li');
@@ -949,6 +919,29 @@ export class NvFieldmultiselect {
             divider.style.display = 'none';
         }
     }
+    /**
+     * Synchronizes the checked state of all child nv-fielddropdownitemcheck components
+     * with the current selectedValues state.
+     */
+    syncChildComponents() {
+        // Early return if element is not ready
+        if (!this.el || !this.el.isConnected) {
+            return;
+        }
+        const items = Array.from(this.el.querySelectorAll('nv-fielddropdownitemcheck'));
+        items.forEach(item => {
+            // Get the effective value: use explicit value if present, otherwise use label
+            const itemValue = item.getAttribute('value') || item.getAttribute('label') || '';
+            if (this.value.includes(itemValue)) {
+                item.setAttribute('checked', '');
+                item.checked = true;
+            }
+            else {
+                item.removeAttribute('checked');
+                item.checked = false;
+            }
+        });
+    }
     /**
      * Renders description and error description sections
      * @returns {any} The JSX for descriptions
@@ -1104,23 +1097,22 @@ export class NvFieldmultiselect {
                 "defaultValue": "'off'"
             },
             "value": {
-                "type": "string",
+                "type": "unknown",
                 "mutable": true,
                 "complexType": {
-                    "original": "string",
-                    "resolved": "string",
+                    "original": "string[]",
+                    "resolved": "string[]",
                     "references": {}
                 },
                 "required": false,
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Specifies the value of the input field."
+                    "text": "Specifies the selected values of the multiselect field.\nThis is the canonical value for the component and is used for form submission."
                 },
                 "getter": false,
                 "setter": false,
-                "attribute": "value",
-                "reflect": true
+                "defaultValue": "[]"
             },
             "required": {
                 "type": "boolean",
@@ -1409,13 +1401,31 @@ export class NvFieldmultiselect {
                 "attribute": "badge-label",
                 "reflect": true,
                 "defaultValue": "''"
+            },
+            "filterText": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "The text entered by the user for filtering multiselect items."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "filter-text",
+                "reflect": true,
+                "defaultValue": "''"
             }
         };
     }
     static get states() {
         return {
-            "filterText": {},
-            "selectedValues": {},
             "sortedOptions": {},
             "isHandlingEscape": {}
         };
@@ -1432,26 +1442,26 @@ export class NvFieldmultiselect {
                             "name": "bind",
                             "text": "value"
                         }],
-                    "text": "Emitted when the input value changes."
+                    "text": "Emitted when the selected values change."
                 },
                 "complexType": {
-                    "original": "string",
-                    "resolved": "string",
+                    "original": "string[]",
+                    "resolved": "string[]",
                     "references": {}
                 }
             }, {
-                "method": "multiselectChange",
-                "name": "multiselectChange",
+                "method": "filterTextChanged",
+                "name": "filterTextChanged",
                 "bubbles": true,
                 "cancelable": true,
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "Event emitted when the selection changes in the multiselect.\nEmits the current list of selected values."
+                    "text": "Emitted when the filter text changes."
                 },
                 "complexType": {
-                    "original": "string[]",
-                    "resolved": "string[]",
+                    "original": "string",
+                    "resolved": "string",
                     "references": {}
                 }
             }];