@kubex/zinc 1.0.25 → 1.0.99

package/src/components/select/select.component.ts

@@ -14,11 +14,12 @@ import {watch} from '../../internal/watch';
 import ZincElement from '../../internal/zinc-element';
 import ZnChip from "../chip";
 import ZnIcon from "../icon";
+import ZnOptGroup from "../opt-group";
+import ZnOption from "../option";
 import ZnPopup from "../popup";
 import type {CSSResultGroup, PropertyValues, TemplateResult} from 'lit';
 import type {ZincFormControl} from '../../internal/zinc-element';
 import type {ZnRemoveEvent} from "../../events/zn-remove";
-import type ZnOption from "../option";
 
 import styles from './select.scss';
 
@@ -29,10 +30,12 @@ import styles from './select.scss';
  * @since 1.0
  *
  * @dependency zn-icon
+ * @dependency zn-opt-group
+ * @dependency zn-option
  * @dependency zn-popup
  * @dependency zn-tag
  *
- * @slot - The listbox options. Must be `<zn-option>` elements. You can use `<zn-divider>` to group items visually.
+ * @slot - The listbox options. Must be `<zn-option>` elements. You can use `<zn-opt-group>` to group options under a labeled header, or `<zn-divider>` to group items visually.
  * @slot label - The input's label. Alternatively, you can use the `label` attribute.
  * @slot label-tooltip - Used to add text that is displayed in a tooltip next to the label. Alternatively, you can use the `label-tooltip` attribute.
  * @slot context-note - Used to add contextual text that is displayed above the select, on the right. Alternatively, you can use the `context-note` attribute.
@@ -51,7 +54,11 @@ import styles from './select.scss';
  * @event zn-hide - Emitted when the select's menu closes.
  * @event zn-after-hide - Emitted after the select's menu closes and all animations are complete.
  * @event zn-invalid - Emitted when the form control has been checked for validity and its constraints aren't satisfied.
+ * @event zn-load - Emitted when options have been successfully loaded from the `src` URL.
+ * @event zn-error - Emitted when loading options from the `src` URL fails.
  *
+ * @csspart search-loading - The container shown while a remote search request is in flight.
+ * @csspart max-results-indicator - The message shown when results are truncated by `max-results`.
  * @csspart form-control - The form control that wraps the label, input, and help text.
  * @csspart form-control-label - The label's wrapper.
  * @csspart form-control-input - The select's wrapper.
@@ -73,6 +80,8 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
   static styles: CSSResultGroup = unsafeCSS(styles);
   static dependencies = {
     'zn-icon': ZnIcon,
+    'zn-opt-group': ZnOptGroup,
+    'zn-option': ZnOption,
     'zn-popup': ZnPopup,
     'zn-tag': ZnChip
   };
@@ -100,26 +109,86 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
   @state() private valueHasChanged: boolean = false;
   @state() private inputPrefix: boolean = false;
 
+  /** @internal - current search/filter text when search is enabled (lowercased for matching) */
+  private _searchQuery = '';
+
+  /** @internal - raw display value of the search input (preserves case for the input field) */
+  private _searchDisplayValue = '';
+
+  /** @internal - whether the "no matching options" empty state is visible */
+  @state() private _noResultsVisible = false;
+
+  /** @internal */
+  @state() private _fetchedOptions: ({ key: string; value: string; group?: undefined } | {
+    group: string;
+    options: { key: string; value: string }[]
+  })[] = [];
+
+  /** @internal */
+  @state() private _fetchLoading = false;
+
+  /** @internal */
+  @state() private _fetchError = '';
+
+  /** @internal */
+  private _fetchAbortController: AbortController | null = null;
+
+  /** @internal - debounce timer for remote search */
+  private _searchDebounceTimer: number | null = null;
+
+  /** @internal - whether a remote search fetch is in progress (distinct from initial load) */
+  @state() private _searchLoading = false;
+
+  /** @internal - the query string of the last successful remote search */
+  private _lastRemoteQuery: string | null = null;
+
+  /** @internal - whether the last remote result set was exhaustive (fewer than maxResults returned) */
+  private _lastRemoteExhaustive = false;
+
+  /** @internal - total number of results before maxResults truncation (0 = not truncated) */
+  @state() private _totalResultCount = 0;
+
+  /**
+   * @internal - tracks selected items by key/value during remote search so they survive
+   * when search results replace the fetched options list.
+   */
+  private _selectedRemoteItems: { key: string; value: string }[] = [];
+
   /** The name of the select, submitted as a name/value pair with form data. */
   @property() name = '';
 
+  @property({type: Boolean, attribute: "non-removable"}) nonRemovable = false;
+
   private _value: string | string[] = '';
 
   get value() {
-    return this._value
+    return this._value;
   }
 
   /**
    * The current value of the select, submitted as a name/value pair with form data. When `multiple` is enabled, the
-   * value attribute will be a space-delimited list of values based on the options selected, and the value property will
-   * be an array. **For this reason, values must not contain spaces.**
+   * value property will be an array. Values may contain spaces when using JSON array syntax in the attribute,
+   * e.g. `value='["my value", "their value"]'`. Space-delimited strings are still supported for backward compatibility.
    */
   @state()
   set value(val: string | string[]) {
     if (this.multiple) {
-      val = Array.isArray(val) ? val : val.split(' ');
+      if (Array.isArray(val)) {
+        // Already an array, keep as-is
+      } else if (val.trimStart().startsWith('[')) {
+        try {
+          const parsed = JSON.parse(val) as unknown;
+          val = Array.isArray(parsed) ? parsed : val.split(" ");
+        } catch {
+          if (typeof val === "string") {
+            val = val.split(" ");
+          }
+        }
+      } else {
+        val = val.split(" ");
+      }
     } else {
-      val = Array.isArray(val) ? val.join(' ') : val;
+      val = Array.isArray(val) ? val.join(" ") : val;
     }
 
     if (this._value === val) {
@@ -128,6 +197,10 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
 
     this.valueHasChanged = true;
     this._value = val;
+
+    if (this.hasUpdated) {
+      this.updateDependencies();
+    }
   }
 
   /** The default value of the form control. Primarily used for resetting the form control. */
@@ -135,15 +208,30 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     attribute: 'value',
     converter: {
       fromAttribute: (value) => {
-        if (!value || Array.isArray(value)) return value
+        if (!value || Array.isArray(value)) return value;
+
+        // Auto-detect JSON array syntax: value='["my value", "their value"]'
+        if (value.trimStart().startsWith('[')) {
+          try {
+            const parsed = JSON.parse(value) as unknown;
+            if (Array.isArray(parsed)) return parsed as string[];
+          } catch {
+            // Not valid JSON, fall through to space-delimited parsing
+          }
+        }
+
         return value.includes(' ') ? value.split(' ') : value;
       },
       toAttribute: (value) => {
+        if (Array.isArray(value) && value.some((v: string) => v.includes(' '))) {
+          return JSON.stringify(value);
+        }
         return Array.isArray(value) ? value.join(' ') : value;
       }
     }
   }) defaultValue: string | string[] = '';
 
+
   /** The select's size. */
   @property({reflect: true}) size: 'small' | 'medium' | 'large' = 'medium';
 
@@ -183,6 +271,9 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
   /** Draws a pill-style select with rounded edges. */
   @property({type: Boolean, reflect: true}) pill = false;
 
+  /** Enables search/filter functionality. When enabled, the user can type into the select to filter the visible options. */
+  @property({type: Boolean, reflect: true}) search = false;
+
   /** The select's label. If you need to display HTML, use the `label` slot instead. */
   @property() label = '';
 
@@ -232,19 +323,59 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
         ?pill=${this.pill}
         size="x-small"
         type="primary"
-        removable
         @zn-remove=${(event: ZnRemoveEvent) => this.handleTagRemove(event, option)}>
         ${option.getTextLabel()}
-        <zn-icon slot="action" src="close" size="16"
-                 @click=${(e: any) => this.handleTagRemove(e as ZnRemoveEvent, option)}></zn-icon>
+        ${(!this.nonRemovable) ? html`
+          <zn-icon slot="action" src="close" size="16"
+                   @click=${(e: any) => this.handleTagRemove(e as ZnRemoveEvent, option)}></zn-icon>` : nothing}
       </zn-chip>
     `;
   };
 
+  /** Automatically select the first option if no value is set. */
+  @property({attribute: 'select-first', type: Boolean}) selectFirst = false;
+
   @property() distinct = "";
 
   @property() conditional = "";
 
+  /**
+   * The URL to fetch options from. When set, the component fetches JSON from this URL and renders the results as
+   * options. The expected format is an array of objects with `key` and `value` properties:
+   * `[{"key": "us", "value": "United States"}, ...]`
+   * When not set, the component works exactly as before using slotted `<zn-option>` elements.
+   */
+  @property({attribute: 'data-uri'}) dataUri: string;
+
+  /**
+   * Context data to send as a header when fetching options from the URL specified by the `src` property.
+   */
+  @property({attribute: 'context-data'}) contextData: string;
+
+  /**
+   * The maximum number of options to display from a remote fetch response. Set to 0 for unlimited.
+   * Only applies when fetching from `data-uri`.
+   */
+  @property({attribute: 'max-results', type: Number}) maxResults = 0;
+
+  /**
+   * Debounce delay in milliseconds for remote search requests. The component waits this long after the user
+   * stops typing before sending a request.
+   */
+  @property({attribute: 'search-debounce', type: Number}) searchDebounce = 300;
+
+  /**
+   * The query parameter name appended to the `data-uri` URL for remote search requests.
+   * Defaults to `"q"`, e.g. `/api/items?q=search+term`. Set to a custom value like `"search"` or `"filter"` to match your API.
+   */
+  @property({attribute: 'search-param'}) searchParam = 'q';
+
+  /**
+   * When set alongside `search` and `data-uri`, the component will not fetch options on initial load.
+   * Options are only fetched when the user starts typing a search query.
+   */
+  @property({attribute: 'search-only', type: Boolean}) searchOnly = false;
+
   /** Gets the validity state object */
   get validity() {
     return this.valueInput?.validity;
@@ -264,13 +395,23 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     this.open = false;
 
     if (this.cacheKey) {
-      const cache: any = JSON.parse(localStorage.getItem('zn-linked-select-cache') || '{}');
+      const cache = JSON.parse(localStorage.getItem('zn-linked-select-cache') || '{}') as Record<string, string | string[]>;
       if (cache[this.cacheKey]) {
         this.value = cache[this.cacheKey];
       }
     }
   }
 
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._fetchAbortController?.abort();
+    this._fetchAbortController = null;
+    if (this._searchDebounceTimer !== null) {
+      clearTimeout(this._searchDebounceTimer);
+      this._searchDebounceTimer = null;
+    }
+  }
+
   private updateHasInputPrefix() {
     const assigned = this.prefixSlot?.assignedElements({flatten: true}) || [];
     this.inputPrefix = assigned.length > 0;
@@ -287,7 +428,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
       this.closeWatcher = new CloseWatcher();
       this.closeWatcher.onclose = () => {
         if (this.open) {
-          this.hide();
+          this.hide().then();
           this.displayInput.focus({preventScroll: true});
         }
       };
@@ -314,11 +455,11 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     this.emit('zn-blur');
   }
 
-  private handleDocumentFocusIn = (event: KeyboardEvent) => {
+  private handleDocumentFocusIn = (event: FocusEvent) => {
     // Close when focusing out of the select
     const path = event.composedPath();
     if (this && !path.includes(this)) {
-      this.hide();
+      this.hide().then();
     }
   };
 
@@ -339,19 +480,19 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     if ((event.key === 'Escape' || event.key === 'Tab') && this.open && !this.closeWatcher) {
       event.preventDefault();
       event.stopPropagation();
-      this.hide();
+      this.hide().then();
       this.displayInput.focus({preventScroll: true});
     }
 
     // Handle enter and space. When pressing space, we allow for type to select behaviors so if there's anything in the
-    // buffer we _don't_ close it.
-    if (event.key === 'Enter' || (event.key === ' ' && this.typeToSelectString === '')) {
+    // buffer we _don't_ close it. When search is enabled, space should type into the input, not toggle.
+    if (event.key === 'Enter' || (event.key === ' ' && !this.search && this.typeToSelectString === '')) {
       event.preventDefault();
       event.stopImmediatePropagation();
 
       // If it's not open, open it
       if (!this.open) {
-        this.show();
+        this.show().then();
         return;
       }
 
@@ -364,6 +505,14 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
           this.setSelectedOptions(this.currentOption);
         }
 
+        // Clear search after keyboard selection
+        if (this.search) {
+          this.clearSearch();
+          if (this.multiple) {
+            this.displayInput.value = '';
+          }
+        }
+
         // Emit after updating
         this.updateComplete.then(() => {
           this.emit('zn-input');
@@ -371,8 +520,14 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
         });
 
         if (!this.multiple) {
-          this.hide();
+          this.hide().then();
           this.displayInput.focus({preventScroll: true});
+        } else if (this.search) {
+          // In multi-select + search, re-focus the search input after keyboard selection
+          this.updateComplete.then(() => {
+            this.displayInput.value = '';
+            this.displayInput.focus({preventScroll: true});
+          });
         }
       }
 
@@ -381,8 +536,8 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
 
     // Navigate options
     if (['ArrowUp', 'ArrowDown', 'Home', 'End'].includes(event.key)) {
-      const allOptions = this.getAllOptions();
-      const currentIndex = allOptions.indexOf(this.currentOption);
+      const navOptions = this.search ? this.getVisibleOptions() : this.getAllOptions();
+      const currentIndex = navOptions.indexOf(this.currentOption);
       let newIndex = Math.max(0, currentIndex);
 
       // Prevent scrolling
@@ -390,7 +545,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
 
       // Open it
       if (!this.open) {
-        this.show();
+        this.show().then();
 
         // If an option is already selected, stop here because we want that one to remain highlighted when the listbox
         // opens for the first time
@@ -401,17 +556,22 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
 
       if (event.key === 'ArrowDown') {
         newIndex = currentIndex + 1;
-        if (newIndex > allOptions.length - 1) newIndex = 0;
+        if (newIndex > navOptions.length - 1) newIndex = 0;
       } else if (event.key === 'ArrowUp') {
         newIndex = currentIndex - 1;
-        if (newIndex < 0) newIndex = allOptions.length - 1;
+        if (newIndex < 0) newIndex = navOptions.length - 1;
       } else if (event.key === 'Home') {
         newIndex = 0;
       } else if (event.key === 'End') {
-        newIndex = allOptions.length - 1;
+        newIndex = navOptions.length - 1;
       }
 
-      this.setCurrentOption(allOptions[newIndex]);
+      this.setCurrentOption(navOptions[newIndex]);
+    }
+
+    // When search is enabled, let the input handle keystrokes natively (they go through handleSearchInput)
+    if (this.search) {
+      return;
     }
 
     // All other "printable" keys trigger type to select
@@ -429,7 +589,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
           return;
         }
 
-        this.show();
+        this.show().then();
       }
 
       event.stopPropagation();
@@ -459,7 +619,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     // Close when clicking outside of the select
     const path = event.composedPath();
     if (this && !path.includes(this)) {
-      this.hide();
+      this.hide().then();
     }
   };
 
@@ -475,8 +635,15 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     const isExpandIcon = path.some(el => el instanceof Element && el.classList.contains('select__expand-icon'));
     // if click is inside the prefix area (e.g. checkbox), don't toggle the select
     const inPrefix = path.some(el => el instanceof Element && el.classList.contains('select__prefix'));
-    // Ignore disabled controls and clicks on tags (remove buttons)
-    if (((this.disabled || isIcon) && !isExpandIcon) || inPrefix) {
+    // Ignore disabled controls, fetch loading/error, and clicks on tags (remove buttons)
+    if (((this.disabled || this._fetchLoading || this._fetchError || isIcon) && !isExpandIcon) || inPrefix) {
+      return;
+    }
+
+    // When search is enabled, clicking the input area should open (not toggle) so the user can type
+    if (this.search && this.open && !isExpandIcon) {
+      event.preventDefault();
+      this.displayInput.focus({preventScroll: true});
       return;
     }
 
@@ -504,6 +671,11 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     event.stopPropagation();
 
     if (this.value !== '') {
+      if (this.search) {
+        this.clearSearch();
+        this.displayInput.value = '';
+      }
+
       this.setSelectedOptions([]);
       this.displayInput.focus({preventScroll: true});
 
@@ -522,29 +694,157 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     event.preventDefault();
   }
 
+  /** Whether the component is in remote-search mode (search + dataUri both set) */
+  private get _isRemoteSearch() {
+    return this.search && !!this.dataUri;
+  }
+
+  /** Handles text input on the display input for search/filter mode */
+  private handleSearchInput() {
+    if (!this.search) return;
+
+    this._searchDisplayValue = this.displayInput.value;
+    this._searchQuery = this._searchDisplayValue.toLowerCase();
+
+    // Open the dropdown when the user starts typing
+    if (!this.open) {
+      this.show().then();
+    }
+
+    if (this._isRemoteSearch) {
+      // Cancel any pending request when the query changes
+      if (this._searchDebounceTimer !== null) {
+        clearTimeout(this._searchDebounceTimer);
+        this._searchDebounceTimer = null;
+      }
+
+      // Empty query — just show all current options, no fetch needed
+      if (!this._searchQuery) {
+        this.filterOptions();
+        return;
+      }
+
+      // If the new query is a refinement of the last one and we know the server had no more
+      // results to give (i.e. it returned fewer than maxResults), we can filter locally instead
+      // of making another round-trip.
+      const canFilterLocally = this._lastRemoteExhaustive
+        && this._lastRemoteQuery !== null
+        && this._searchQuery.startsWith(this._lastRemoteQuery);
+
+      if (canFilterLocally) {
+        this.filterOptions();
+        return;
+      }
+
+      // Remote search: debounce and fetch from server
+      this._noResultsVisible = false;
+      this._searchDebounceTimer = window.setTimeout(() => {
+        this._searchDebounceTimer = null;
+        this.fetchOptions(this._searchQuery).then();
+      }, this.searchDebounce);
+    } else {
+      // Local search: filter existing options
+      this.filterOptions();
+    }
+  }
+
+  /** Filters visible options based on the current search query */
+  private filterOptions() {
+    const allOptions = this.getAllOptions();
+    const searchQuery = this._searchQuery;
+
+    if (!searchQuery) {
+      // Show all options and opt-groups
+      allOptions.forEach(option => {
+        option.hidden = false;
+      });
+      this.getAllOptGroups().forEach(group => {
+        group.hidden = false;
+      });
+      this._noResultsVisible = false;
+      return;
+    }
+
+    allOptions.forEach(option => {
+      // Don't un-hide selected options that are only in the DOM for value preservation
+      if (option.selected && option.hidden) return;
+
+      const label = option.getTextLabel().toLowerCase();
+      const value = option.value.toLowerCase();
+      const matches = label.includes(searchQuery) || value.includes(searchQuery);
+      option.hidden = !matches;
+    });
+
+    // Update opt-group visibility based on whether any child options are visible
+    this.getAllOptGroups().forEach(group => group.updateVisibility());
+
+    // Show empty state when no non-selected options match (selected-but-hidden items are value anchors, not results)
+    this._noResultsVisible = allOptions.filter(o => !o.selected).every(option => option.hidden);
+
+    // Reset current option if it's now hidden
+    if (this.currentOption && this.currentOption.hidden) {
+      const firstVisible = allOptions.find(o => !o.hidden && !o.disabled);
+      if (firstVisible) {
+        this.setCurrentOption(firstVisible);
+      }
+    }
+  }
+
+  /** Clears the search query and shows all options */
+  private clearSearch() {
+    this._searchQuery = '';
+    this._searchDisplayValue = '';
+    this._noResultsVisible = false;
+
+    // Cancel any pending remote search
+    if (this._searchDebounceTimer !== null) {
+      clearTimeout(this._searchDebounceTimer);
+      this._searchDebounceTimer = null;
+    }
+    this._searchLoading = false;
+
+    const allOptions = this.getAllOptions();
+    allOptions.forEach(option => {
+      option.hidden = false;
+    });
+    // Also unhide any opt-groups that were hidden during filtering
+    this.getAllOptGroups().forEach(group => {
+      group.hidden = false;
+    });
+  }
+
   private handleOptionClick(event: MouseEvent) {
     const target = event.target as HTMLElement;
     const option = target.closest('zn-option');
     const oldValue = this.value;
 
     if (option && !option.disabled) {
-      this.valueHasChanged = true
+      this.valueHasChanged = true;
       if (this.multiple) {
-        if (this.maxOptions > 0) {
-          if (this.selectedOptions.length >= this.maxOptions && !option.selected) {
-            return;
-          }
-
-          this.toggleOptionSelection(option);
-        } else {
-          this.toggleOptionSelection(option)
+        if (this.maxOptions > 0 && this.selectedOptions.length >= this.maxOptions && !option.selected) {
+          return;
         }
+        this.toggleOptionSelection(option);
       } else {
         this.setSelectedOptions(option);
       }
 
+      // Clear search after selection when in search mode
+      if (this.search) {
+        this.clearSearch();
+        if (this.multiple) {
+          // Keep the search input clear for further typing
+          this.displayInput.value = '';
+        }
+      }
+
       // Set focus after updating so the value is announced by screen readers
-      this.updateComplete.then(() => this.displayInput.focus({preventScroll: true}));
+      this.updateComplete.then(() => {
+        if (this.multiple && this.search && this.open) {
+          this.displayInput.value = '';
+        }
+        this.displayInput.focus({preventScroll: true});
+      });
 
       if (this.value !== oldValue) {
         // Emit after updating
@@ -555,7 +855,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
       }
 
       if (!this.multiple) {
-        this.hide();
+        this.hide().then();
         this.displayInput.focus({preventScroll: true});
       }
 
@@ -593,6 +893,14 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
         }
       }
     }
+
+    // Auto-select the first option if selectFirst is enabled and no value is set
+    if (this.selectFirst && this.selectedOptions.length === 0 && allOptions.length > 0) {
+      this.setSelectedOptions(allOptions[0]);
+      this.valueHasChanged = true;
+      this.emit('zn-input');
+      this.emit('zn-change');
+    }
   }
 
   private handleTagRemove(event: ZnRemoveEvent, option: ZnOption) {
@@ -610,9 +918,27 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     }
   }
 
-  // Gets an array of all <zn-option> elements
+  // Gets an array of all <zn-option> elements (both fetched in shadow DOM and slotted in light DOM)
   private getAllOptions() {
-    return [...this.querySelectorAll<ZnOption>('zn-option')];
+    const shadowOptions = this.shadowRoot
+      ? [...this.shadowRoot.querySelectorAll<ZnOption>('.select__listbox zn-option')]
+      : [];
+    const slottedOptions = [...this.querySelectorAll<ZnOption>('zn-option')];
+    return [...shadowOptions, ...slottedOptions];
+  }
+
+  // Gets an array of all <zn-opt-group> elements (both in shadow DOM and slotted in light DOM)
+  private getAllOptGroups() {
+    const shadowGroups = this.shadowRoot
+      ? [...this.shadowRoot.querySelectorAll<ZnOptGroup>('.select__listbox zn-opt-group')]
+      : [];
+    const slottedGroups = [...this.querySelectorAll<ZnOptGroup>('zn-opt-group')];
+    return [...shadowGroups, ...slottedGroups];
+  }
+
+  // Gets an array of visible (not hidden) <zn-option> elements, used by keyboard navigation when search is active
+  private getVisibleOptions() {
+    return this.getAllOptions().filter(option => !option.hidden);
   }
 
   // Gets the first <zn-option> element
@@ -631,13 +957,16 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
       el.tabIndex = -1;
     });
 
-
     // Select the target option
     if (option) {
       this.currentOption = option;
       option.current = true;
       option.tabIndex = 0;
-      option.focus();
+      // When search is active and the display input has focus, don't steal focus to the option.
+      // The user is typing in the search input and we only want to visually highlight the current option.
+      if (!(this.search && this.open && this.shadowRoot?.activeElement === this.displayInput)) {
+        option.focus();
+      }
     }
   }
 
@@ -675,23 +1004,35 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     // Update selected options cache
     this.selectedOptions = this.getAllOptions().filter(el => el.selected);
 
+    // In remote-search + multiple mode, track selected items so they persist across search result changes
+    if (this._isRemoteSearch && this.multiple) {
+      this._selectedRemoteItems = this.selectedOptions.map(el => ({
+        key: el.value,
+        value: el.getTextLabel()
+      }));
+    }
+
     // Keep a reference to the previous `valueHasChanged`. Changes made here don't count has changing the value.
     const cachedValueHasChanged: boolean = this.valueHasChanged;
 
     // Update the value and display label
     if (this.multiple) {
-      this.getAllOptions().filter(el => el.multiple !== true).forEach(el => el.multiple = true);
+      this.getAllOptions().filter(el => !el.multiple).forEach(el => {
+        el.multiple = true;
+      });
 
       this.value = this.selectedOptions.map(el => el.value);
 
-      if (this.placeholder && this.value.length === 0) {
+      if (this.value.length === 0) {
         // When no items are selected, keep the value empty so the placeholder shows
         this.displayLabel = '';
       } else {
         this.displayLabel = this.localize.term('numOptionsSelected', this.selectedOptions.length);
       }
     } else {
-      this.getAllOptions().filter(el => el.multiple === true).forEach(el => el.multiple = false);
+      this.getAllOptions().filter(el => el.multiple).forEach(el => {
+        el.multiple = false;
+      });
       const selectedOption = this.selectedOptions[0];
       this.value = selectedOption?.value ?? '';
       this.displayLabel = selectedOption?.getTextLabel() ?? '';
@@ -722,6 +1063,33 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     });
   }
 
+  /**
+   * Renders hidden <zn-option> elements for items that are currently selected but not present in
+   * the latest `_fetchedOptions` (e.g. because a remote search narrowed the results). This keeps
+   * them in the DOM so `handleDefaultSlotChange` can find and re-select them.
+   */
+  private _renderSelectedRemoteItems() {
+    if (!this._isRemoteSearch || !this.multiple || this._selectedRemoteItems.length === 0) {
+      return nothing;
+    }
+
+    // Build a set of keys present in the current fetched options
+    const fetchedKeys = new Set<string>();
+    for (const item of this._fetchedOptions) {
+      if (item.group !== undefined) {
+        for (const opt of item.options) fetchedKeys.add(opt.key);
+      } else {
+        fetchedKeys.add(item.key);
+      }
+    }
+
+    // Render hidden options for selected items not in the fetched results
+    return this._selectedRemoteItems
+      .filter(item => !fetchedKeys.has(item.key))
+      .map(item => html`
+        <zn-option value=${item.key} hidden>${item.value}</zn-option>`);
+  }
+
   private handleInvalid(event: Event) {
     this.formControlController.setValidity(false);
     this.formControlController.emitInvalidEvent(event);
@@ -732,7 +1100,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
 
     if (this.distinct !== "") {
       // if we are linked to another zn-data-select remove the selected values from that select from this select
-      const linkedSelect = document.querySelector(`zn-select[id="${this.distinct}"]`) as ZnSelect;
+      const linkedSelect = document.querySelector<ZnSelect>(`zn-select[id="${this.distinct}"]`)!;
       if (linkedSelect) {
         linkedSelect.addEventListener('zn-change', () => {
           const linkedValues = Array.isArray(linkedSelect.value) ? linkedSelect.value : [linkedSelect.value];
@@ -753,30 +1121,269 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     }
 
     if (this.conditional !== "") {
-      const conditionalSelectList = deepQuerySelectorAll(`#${this.conditional}`, document.documentElement, '') as ZnSelect[];
-      conditionalSelectList.forEach((conditionalSelect) => {
-        // disable if the other has any options selected
-        conditionalSelect.addEventListener('zn-change', () => {
-          let linkedValues = Array.isArray(conditionalSelect.value) ? conditionalSelect.value : [conditionalSelect.value];
+      const ids = this.conditional.split(',').map(id => id.trim());
+      const conditionals: ZnSelect[] = [];
+
+      ids.forEach(id => {
+        const elements = deepQuerySelectorAll(`#${id}`, document.documentElement, '') as ZnSelect[];
+        conditionals.push(...elements);
+      });
+
+      const initiallyDisabled = this.disabled;
+      const checkConditionals = () => {
+        const shouldDisable = conditionals.some(select => {
+          let linkedValues = Array.isArray(select.value) ? select.value : [select.value];
           linkedValues = linkedValues.filter(v => v !== '');
-          console.log('linkedValues', linkedValues);
-          this.disabled = linkedValues.length > 0;
+          return linkedValues.length > 0;
         });
+        this.disabled = initiallyDisabled || shouldDisable;
+      };
 
-        // trigger the event once to initialize
-        conditionalSelect.dispatchEvent(new Event('zn-input'));
+      conditionals.forEach(select => {
+        select.addEventListener('zn-change', checkConditionals);
+        select.addEventListener('zn-input', checkConditionals);
       });
+
+      // trigger the check once to initialize
+      checkConditionals();
+    }
+
+    if (this.dataUri && !this.searchOnly) {
+      this.fetchOptions().then();
     }
 
     this.updateHasInputPrefix();
+    this.updateDependencies();
   }
 
   @watch('disabled', {waitUntilFirstUpdate: true})
   handleDisabledChange() {
-    // Close the listbox when the control is disabled
     if (this.disabled) {
+      // Close the listbox and abort any in-progress fetch
       this.open = false;
-      this.handleOpenChange();
+      this.handleOpenChange().then();
+      this._fetchAbortController?.abort();
+      this._fetchAbortController = null;
+      this._fetchLoading = false;
+      this._fetchError = '';
+    } else if (this.dataUri && !this.searchOnly) {
+      // Fetch options when enabled
+      this.fetchOptions().then();
+    }
+  }
+
+  @watch(['dataUri', 'contextData'], {waitUntilFirstUpdate: true})
+  handleSrcChange() {
+    if (this.dataUri && !this.searchOnly) {
+      this.fetchOptions().then();
+    } else {
+      this._fetchedOptions = [];
+      this._fetchLoading = false;
+      this._fetchError = '';
+      this.handleDefaultSlotChange();
+    }
+  }
+
+  private _handleFetchError(message: string) {
+    this._fetchError = message;
+    this._fetchLoading = false;
+    this._fetchAbortController = null;
+    this.emit('zn-error', {detail: {status: 400}});
+  }
+
+  /** Builds the localStorage cache key for a given search query */
+  private _buildCacheKey(searchQuery?: string): string {
+    const base = this.cacheKey || this.dataUri;
+    return searchQuery ? `zn-select-search:${base}:${searchQuery}` : `zn-select-search:${base}`;
+  }
+
+  /** Reads cached results from localStorage */
+  private _readCache(searchQuery?: string): typeof this._fetchedOptions | null {
+    if (!this.cacheKey) return null;
+    try {
+      const raw = localStorage.getItem(this._buildCacheKey(searchQuery));
+      if (raw) return JSON.parse(raw) as typeof this._fetchedOptions;
+    } catch {
+      // Ignore corrupt cache
+    }
+    return null;
+  }
+
+  /** Writes results to localStorage cache */
+  private _writeCache(searchQuery: string | undefined, data: typeof this._fetchedOptions) {
+    if (!this.cacheKey) return;
+    try {
+      localStorage.setItem(this._buildCacheKey(searchQuery), JSON.stringify(data));
+    } catch {
+      // Storage full or unavailable — silently ignore
+    }
+  }
+
+  /**
+   * Parses raw JSON data into the internal fetched-options format.
+   * Applies `maxResults` limiting to flat option arrays.
+   */
+  private _parseOptions(data: unknown): typeof this._fetchedOptions | null {
+    type FetchedOption = { key: string; value: string; group?: undefined };
+    type FetchedGroup = { group: string; options: { key: string; value: string }[] };
+    let options: (FetchedOption | FetchedGroup)[];
+
+    if (Array.isArray(data)) {
+      const isGrouped = data.length > 0 && data.some(
+        (item: unknown) => item && typeof item === 'object' && 'group' in (item as Record<string, unknown>)
+      );
+
+      if (isGrouped) {
+        options = (data as Record<string, unknown>[]).map(item => {
+          if ('group' in item && Array.isArray(item.options)) {
+            return {
+              group: String(item.group),
+              options: item.options as { key: string; value: string }[]
+            } as FetchedGroup;
+          }
+          return item as unknown as FetchedOption;
+        });
+      } else {
+        options = data as FetchedOption[];
+      }
+    } else if (data && typeof data === 'object') {
+      options = Object.entries(data as Record<string, unknown>).map(([key, value]) => ({
+        key,
+        value: String(value)
+      }));
+    } else {
+      return null;
+    }
+
+    // Apply max-results limit to flat (non-grouped) options
+    if (this.maxResults > 0) {
+      let count = 0;
+      const limited: (FetchedOption | FetchedGroup)[] = [];
+      for (const item of options) {
+        if (count >= this.maxResults) break;
+        if (item.group !== undefined) {
+          const remaining = this.maxResults - count;
+          const slicedOpts = item.options.slice(0, remaining);
+          if (slicedOpts.length > 0) {
+            limited.push({group: item.group, options: slicedOpts});
+            count += slicedOpts.length;
+          }
+        } else {
+          limited.push(item);
+          count++;
+        }
+      }
+      options = limited;
+    }
+
+    return options;
+  }
+
+  /** Fetches options from the URL specified by the `data-uri` property. Optionally appends a search query. */
+  async fetchOptions(searchQuery?: string) {
+    if (!this.dataUri || this.disabled) return;
+
+    const isRemoteSearch = !!searchQuery;
+
+    // Check cache first
+    if (this.cacheKey) {
+      const cached = this._readCache(searchQuery);
+      if (cached) {
+        this._fetchedOptions = cached;
+        this._searchLoading = false;
+        this._fetchLoading = false;
+        this._totalResultCount = 0;
+        this._noResultsVisible = cached.length === 0 && isRemoteSearch;
+        this.emit('zn-load');
+        this.updateComplete.then(() => this.handleDefaultSlotChange());
+        return;
+      }
+    }
+
+    this._fetchAbortController?.abort();
+    this._fetchAbortController = new AbortController();
+
+    if (isRemoteSearch) {
+      this._searchLoading = true;
+    } else {
+      this._fetchLoading = true;
+    }
+    this._fetchError = '';
+
+    try {
+      // Build the URL — append search query as a parameter for remote search
+      let url = this.dataUri;
+      if (searchQuery) {
+        const separator = url.includes('?') ? '&' : '?';
+        url = `${url}${separator}${encodeURIComponent(this.searchParam)}=${encodeURIComponent(searchQuery)}`;
+      }
+
+      const response = await fetch(url, {
+        signal: this._fetchAbortController.signal,
+        credentials: 'same-origin',
+        headers: {
+          'x-kx-fetch-style': 'zn-select-options',
+          'x-kx-context-data': this.contextData || ''
+        },
+      });
+
+      if (!response.ok) {
+        this._searchLoading = false;
+        this._handleFetchError(response.statusText || `HTTP ${response.status}`);
+        return;
+      }
+
+      const data: unknown = await response.json();
+
+      // Count raw results before maxResults limiting to determine exhaustiveness
+      const rawCount = Array.isArray(data)
+        ? data.reduce((n: number, item: unknown) => {
+          if (item && typeof item === 'object' && 'group' in (item as Record<string, unknown>)) {
+            const group = item as Record<string, unknown>;
+            return n + (Array.isArray(group.options) ? group.options.length : 0);
+          }
+          return n + 1;
+        }, 0)
+        : (data && typeof data === 'object') ? Object.keys(data as object).length : 0;
+
+      const options = this._parseOptions(data);
+
+      if (!options) {
+        this._searchLoading = false;
+        this._handleFetchError('Expected JSON array or object of options');
+        return;
+      }
+
+      this._fetchedOptions = options;
+      this._fetchLoading = false;
+      this._searchLoading = false;
+      this._fetchAbortController = null;
+      this._noResultsVisible = options.length === 0 && isRemoteSearch;
+
+      // Track total vs displayed count for truncation indicator
+      this._totalResultCount = this.maxResults > 0 && rawCount > this.maxResults ? rawCount : 0;
+
+      // Track whether the server's result set was exhaustive (returned fewer than the limit).
+      // If so, further refinements of this query can be filtered client-side.
+      // For the initial load (no search query), this tells us if we already have all results.
+      this._lastRemoteQuery = searchQuery ?? '';
+      this._lastRemoteExhaustive = this.maxResults > 0 ? rawCount < this.maxResults : true;
+
+      // Cache the results
+      this._writeCache(searchQuery, options);
+
+      this.emit('zn-load');
+
+      this.updateComplete.then(() => {
+        this.handleDefaultSlotChange();
+      });
+    } catch (error: unknown) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        return;
+      }
+
+      this._searchLoading = false;
+      this._handleFetchError(error instanceof Error ? error.message : 'Failed to load options');
     }
   }
 
@@ -806,6 +1413,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
 
     // Select only the options that match the new value
     this.setSelectedOptions(allOptions.filter(el => value.includes(el.value)));
+    this.updateDependencies();
   }
 
   @watch('open', {waitUntilFirstUpdate: true})
@@ -814,6 +1422,13 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
       // Reset the current option
       this.setCurrentOption(null);
 
+      // When search is enabled, clear the display input to allow typing and show all options
+      if (this.search) {
+        this.clearSearch();
+        this.displayInput.value = '';
+        this.displayInput.readOnly = false;
+      }
+
       // Show
       this.emit('zn-show');
       this.addOpenListeners();
@@ -827,6 +1442,13 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
         this.setCurrentOption(this.currentOption);
       });
 
+      // Focus the search input so the user can start typing immediately
+      if (this.search) {
+        requestAnimationFrame(() => {
+          this.displayInput.focus({preventScroll: true});
+        });
+      }
+
       const {keyframes, options} = getAnimation(this, 'select.show', {dir: this.localize.dir()});
       await animateTo(this.popup.popup, keyframes, options);
 
@@ -841,6 +1463,14 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
       this.emit('zn-hide');
       this.removeOpenListeners();
 
+      // When search is enabled, restore the display label and clear the search
+      if (this.search) {
+        this.clearSearch();
+        this.displayInput.readOnly = true;
+        // In multiple mode, tags show the selection so keep the input empty
+        this.displayInput.value = this.multiple ? '' : this.displayLabel;
+      }
+
       await stopAnimations(this);
       const {keyframes, options} = getAnimation(this, 'select.hide', {dir: this.localize.dir()});
       await animateTo(this.popup.popup, keyframes, options);
@@ -904,6 +1534,67 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     this.displayInput.blur();
   }
 
+  private updateDependencies() {
+    const root = this.getRootNode() as Document | ShadowRoot;
+    if (!root?.querySelectorAll) return;
+
+    const dependentElements = root.querySelectorAll('[data-disable-on]');
+    dependentElements.forEach(el => {
+      const selector = el.getAttribute('data-disable-on');
+      if (!selector) return;
+
+      let trigger: Element | null = null;
+      try {
+        trigger = root.querySelector(selector);
+      } catch (e) {
+        // no-op
+      }
+
+      if (!trigger) {
+        const idSelector = selector.startsWith('#') ? selector : `#${selector}`;
+        try {
+          trigger = root.querySelector(idSelector);
+        } catch (e) {
+          // no-op
+        }
+      }
+
+      if (trigger === this) {
+        this.updateDependencyState(el as HTMLInputElement);
+      }
+    });
+  }
+
+  private updateDependencyState(target: HTMLInputElement) {
+    const disableValue = target.getAttribute('data-disable-value');
+    if (disableValue !== null) {
+      const valuesToCheck = disableValue.split(',').map(v => v.trim());
+      let shouldDisable: boolean;
+
+      if (Array.isArray(this.value)) {
+        shouldDisable = this.value.some(v => valuesToCheck.includes(v));
+      } else {
+        shouldDisable = valuesToCheck.includes(String(this.value));
+      }
+
+      this.toggleDisabled(target, shouldDisable);
+    }
+  }
+
+  private toggleDisabled(target: HTMLInputElement, disabled: boolean) {
+    const reset = () => {
+      if ('defaultValue' in target && typeof target.defaultValue !== 'undefined') {
+        target.value = target.defaultValue;
+      }
+    }
+
+    target.disabled = disabled;
+
+    if (disabled) {
+      reset();
+    }
+  }
+
   render() {
     const hasLabelSlot = this.hasSlotController.test('label');
     const hasLabelTooltipSlot = this.hasSlotController.test('label-tooltip');
@@ -915,6 +1606,8 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
     const hasHelpText = this.helpText ? true : hasHelpTextSlot;
     const hasClearIcon = this.clearable && !this.disabled && this.value.length > 0;
     const isPlaceholderVisible = this.placeholder && this.value.length === 0;
+    const isFetchDisabled = this._fetchLoading || !!this._fetchError;
+    const isDisabled = this.disabled || isFetchDisabled;
 
     return html`
       <div
@@ -958,7 +1651,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
               'select--standard': true,
               'select--pill': this.pill,
               'select--open': this.open,
-              'select--disabled': this.disabled,
+              'select--disabled': isDisabled,
               'select--multiple': this.multiple,
               'select--focused': this.hasFocus,
               'select--placeholder-visible': isPlaceholderVisible,
@@ -967,7 +1660,8 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
               'select--small': this.size === 'small',
               'select--medium': this.size === 'medium',
               'select--large': this.size === 'large',
-              'select--has-input-prefix': this.inputPrefix
+              'select--has-input-prefix': this.inputPrefix,
+              'select--search': this.search
             })}
             placement=${this.placement}
             strategy=${this.hoist ? 'fixed' : 'absolute'}
@@ -991,23 +1685,25 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
                 part="display-input"
                 class="select__display-input"
                 type="text"
-                placeholder=${this.placeholder}
-                .disabled=${this.disabled}
-                .value=${this.displayLabel}
+                placeholder=${this._fetchLoading ? 'Loading...' : this._fetchError ? this._fetchError : (this.search && this.open ? (this.displayLabel || this.placeholder || 'Search...') : this.placeholder)}
+                .disabled=${isDisabled}
+                .value=${isFetchDisabled ? '' : (this.search && this.open) ? this._searchDisplayValue : (this.search && this.multiple) ? '' : this.displayLabel}
                 autocomplete="off"
                 spellcheck="false"
                 autocapitalize="off"
-                readonly
+                ?readonly=${!(this.search && this.open)}
                 aria-controls="listbox"
                 aria-expanded=${this.open ? 'true' : 'false'}
                 aria-haspopup="listbox"
                 aria-labelledby="label"
-                aria-disabled=${this.disabled ? 'true' : 'false'}
+                aria-disabled=${isDisabled ? 'true' : 'false'}
                 aria-describedby="help-text"
+                aria-autocomplete=${this.search ? 'list' : 'none'}
                 role="combobox"
                 tabindex="0"
                 @focus=${this.handleFocus}
                 @blur=${this.handleBlur}
+                @input=${this.handleSearchInput}
               />
 
               ${this.multiple ? html`
@@ -1016,7 +1712,7 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
               <input
                 class="select__value-input"
                 type="text"
-                disabled=${this.disabled || nothing}
+                disabled=${isDisabled || nothing}
                 required=${this.required || nothing}
                 value=${Array.isArray(this.value) ? this.value.join(', ') : this.value}
                 tabindex="-1"
@@ -1041,9 +1737,17 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
                   </button>`
                 : ''}
 
-              <slot name="expand-icon" part="expand-icon" class="select__expand-icon">
-                <zn-icon src="keyboard_arrow_down"></zn-icon>
-              </slot>
+              ${this._fetchLoading
+                ? html`
+                  <zn-icon src="progress_activity" class="select__expand-icon select__spinner"></zn-icon>`
+                : this._fetchError
+                  ? html`
+                    <zn-icon src="error" class="select__expand-icon select__fetch-error-icon"></zn-icon>`
+                  : html`
+                    <slot name="expand-icon" part="expand-icon" class="select__expand-icon">
+                      <zn-icon src="keyboard_arrow_down"></zn-icon>
+                    </slot>`
+              }
             </div>
 
             <div
@@ -1058,6 +1762,42 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
               @mouseup=${this.handleOptionClick}
               @slotchange=${this.handleDefaultSlotChange}>
               <slot></slot>
+              ${this._renderSelectedRemoteItems()}
+              ${this._fetchedOptions.map(item =>
+                item.group !== undefined
+                  ? html`
+                    <zn-opt-group label=${item.group}>
+                      ${item.options.map(
+                        option => html`
+                          <zn-option value=${option.key}>${option.value}</zn-option>`
+                      )}
+                    </zn-opt-group>`
+                  : html`
+                    <zn-option value=${item.key}>${item.value}</zn-option>`
+              )}
+              ${this._totalResultCount > 0
+                ? html`
+                  <div part="max-results-indicator" class="select__max-results-indicator">
+                    Showing ${this.maxResults} of ${this._totalResultCount} results — refine your search for more
+                  </div>`
+                : nothing
+              }
+              ${this._searchLoading
+                ? html`
+                  <div part="search-loading" class="select__search-loading">
+                    <zn-icon src="progress_activity" class="select__spinner"></zn-icon>
+                    Searching...
+                  </div>`
+                : this.searchOnly && this._fetchedOptions.length === 0 && !this._searchQuery
+                  ? html`
+                    <div part="empty-state" class="select__empty-state">
+                      Type to search...
+                    </div>`
+                  : html`
+                    <div part="empty-state" class="select__empty-state" ?hidden=${!this._noResultsVisible}>
+                      No matching options
+                    </div>`
+              }
             </div>
           </zn-popup>
         </div>