@ibobbyts/svelte-ui-utils 0.4.3 → 0.4.5

package/dist/dropdown/Dropdown.svelte

@@ -1,9 +1,19 @@
 <svelte:options runes={false} />
 
+<script context="module" lang="ts">
+  let dropdownInstanceCount = 0;
+</script>
+
 <script lang="ts">
   import { onDestroy, tick } from 'svelte';
+  import { getUiMessages, type UiLanguage } from '../i18n.js';
   import type {
     DropdownChangeHandler,
+    DropdownInputStyle,
+    DropdownItemLabelGetter,
+    DropdownLoadOptions,
+    DropdownLoadOptionsResult,
+    DropdownLoadStatus,
     DropdownMenuAlign,
     DropdownMultiChangeHandler,
     DropdownMultiValue,
@@ -11,6 +21,7 @@
     DropdownOptionGroup,
     DropdownPlacement,
     DropdownSelectionChangeHandler,
+    DropdownSearchChangeHandler,
     DropdownSelection,
     DropdownTriggerClickHandler,
     DropdownValue
@@ -21,7 +32,21 @@
   export let multiselect = false;
   export let options: DropdownOption[] = [];
   export let optionGroups: DropdownOptionGroup[] | undefined = undefined;
+  /** Labels for controlled values that are not present in the current search result. */
+  export let selectedOptions: DropdownOption[] = [];
   export let groupsCollapsedByDefault: 'true' | 'false' | 'auto' = 'false';
+  export let search = false;
+  export let input_style: DropdownInputStyle = 'dropdown';
+  export let getItemLabel: DropdownItemLabelGetter = (option) => option.label;
+  export let loadOptions: DropdownLoadOptions | undefined = undefined;
+  export let searchDebounceMs = 300;
+  export let searchLimit = 10;
+  export let searchPlaceholder: string | undefined = undefined;
+  export let placeholder: string | undefined = undefined;
+  export let language: UiLanguage = 'en_us';
+  export let loadingText: string | undefined = undefined;
+  export let noResultsText: string | undefined = undefined;
+  export let errorText: string | undefined = undefined;
   export let ariaLabel: string | undefined = undefined;
   export let placement: DropdownPlacement = 'auto';
   export let menuAlign: DropdownMenuAlign = 'left';
@@ -36,10 +61,12 @@
   export let className: string | undefined = undefined;
   export let portal = false;
   export let onChange: DropdownSelectionChangeHandler | undefined = undefined;
+  export let onSearchChange: DropdownSearchChangeHandler | undefined = undefined;
   export let onTriggerClick: DropdownTriggerClickHandler | undefined = undefined;
 
   const viewportMargin = 20;
   const menuGap = 6;
+  const instanceId = ++dropdownInstanceCount;
 
   let open = false;
   let activeValue: DropdownValue = '';
@@ -58,22 +85,52 @@
   let typeaheadTimer: ReturnType<typeof setTimeout> | undefined;
   let typeaheadGeneration = 0;
   let collapsedGroupIndexes = new Set<number>();
+  // Whether the current open session has already seeded auto group collapse
+  // from a search response; once true, the user's manual toggles own the set.
+  let searchGroupsInitialized = false;
+  let searchQuery = '';
+  // 在受控 value 尚未响应 onChange 时保留用户当前输入，避免
+  // selectedText 的旧值在同一轮更新中覆盖输入框内容。
+  let inputDraft: string | undefined;
+  let preserveInputDraftOnClose = false;
+  let searchStatus: DropdownLoadStatus = 'idle';
+  let searchOptions: DropdownOption[] = [];
+  let searchOptionGroups: DropdownOptionGroup[] | undefined = undefined;
+  let searchTimer: ReturnType<typeof setTimeout> | undefined;
+  let searchController: AbortController | undefined;
+  let searchRequestId = 0;
+  let searchInputElement: HTMLInputElement | undefined;
+  const knownLabels = new Map<DropdownValue, string>();
   // Keep the buffer long enough for users to type multi-character aliases
   // while the menu is rendering a large option list.
   const typeaheadTimeoutMs = 1000;
 
-  $: resolvedOptions = optionGroups === undefined ? options : optionGroups.flatMap((group) => group.options);
-  $: visibleOptions = optionGroups === undefined
-    ? options
-    : optionGroups.flatMap((group, groupIndex) => group.label && collapsedGroupIndexes.has(groupIndex) ? [] : group.options);
-  $: selectedValues = normalizeSelectedValues(multiselect && Array.isArray(value) ? value : []);
+  $: messages = getUiMessages(language);
+  $: resolvedLoadingText = loadingText?.trim() ? loadingText : messages.dropdownSearch.loadingText;
+  $: resolvedNoResultsText = noResultsText?.trim() ? noResultsText : messages.dropdownSearch.noResultsText;
+  $: resolvedErrorText = errorText?.trim() ? errorText : 'Failed to load options';
+  $: resolvedListboxId = id ? `${id}-listbox` : search ? `suu-dropdown-listbox-${instanceId}` : undefined;
+  // Search results fully replace the instantiated options while searching;
+  // outside of search mode the caller-provided options stay authoritative.
+  $: renderOptions = search ? searchOptions : options;
+  $: renderOptionGroups = search ? searchOptionGroups : optionGroups;
+  $: resolvedOptions = renderOptionGroups === undefined ? renderOptions : renderOptionGroups.flatMap((group) => group.options);
+  $: visibleOptions = renderOptionGroups === undefined
+    ? renderOptions
+    : renderOptionGroups.flatMap((group, groupIndex) => group.label && collapsedGroupIndexes.has(groupIndex) ? [] : group.options);
+  $: trackOptionLabels(resolvedOptions);
+  $: trackOptionLabels(selectedOptions);
+  $: rawSelectedValues = normalizeSelectedValues(multiselect && Array.isArray(value) ? value : []);
+  $: selectedValues = orderSelectedValues(resolvedOptions, rawSelectedValues);
+  $: selectedValueSet = new Set(rawSelectedValues);
   $: selectedOption = Array.isArray(value) ? undefined : resolvedOptions.find((option) => option.value === value);
   $: selectedText = multiselect
-    ? resolvedOptions
-        .filter((option) => selectedValues.includes(option.value))
-        .map((option) => option.label)
-        .join(', ')
-    : selectedOption?.label ?? String(value);
+    ? selectedLabelTexts(selectedValues).join(', ')
+    : displayLabelForValue(Array.isArray(value) ? '' : value);
+  $: inputMode = search && input_style === 'input';
+  $: inputDisplayValue = inputMode
+    ? (inputDraft ?? (searchQuery || (multiselect ? '' : selectedText)))
+    : '';
   $: if (!open) {
     activeValue = initialActiveValue();
   }
@@ -81,13 +138,16 @@
     placement;
     if (open) {
       enableOpenViewportTracking();
-      if (multiselect) {
+      if (multiselect || search) {
         enableOutsidePointerDismissal();
       }
       void updateViewportPanelMaxHeight();
     } else {
       disableOpenViewportTracking();
       disableOutsidePointerDismissal();
+      if (search) {
+        resetSearchOnClose();
+      }
       resolvedPlacement = placement === 'up' ? 'up' : 'down';
       viewportPanelMaxHeight = undefined;
     }
@@ -98,25 +158,90 @@
   }
 
   function normalizeSelectedValues(nextValues: DropdownMultiValue): DropdownMultiValue {
-    const incoming = new Set(nextValues);
+    const seen = new Set<DropdownValue>();
     const normalized: DropdownMultiValue = [];
-    for (const option of resolvedOptions) {
-      if (incoming.has(option.value) && !normalized.includes(option.value)) {
-        normalized.push(option.value);
+    for (const nextValue of nextValues) {
+      if (!seen.has(nextValue)) {
+        seen.add(nextValue);
+        normalized.push(nextValue);
       }
     }
     return normalized;
   }
 
+  // Selected values are reported in option order, but values that are not
+  // present in the current options (e.g. picked during an earlier async
+  // search) are preserved at the end instead of being dropped.
+  function orderSelectedValues(
+    nextOptions: DropdownOption[],
+    nextSelected: DropdownMultiValue
+  ): DropdownMultiValue {
+    const selectedSet = new Set(nextSelected);
+    const ordered = nextOptions
+      .filter((option) => selectedSet.has(option.value))
+      .map((option) => option.value);
+    const orderedSet = new Set(ordered);
+    for (const nextValue of nextSelected) {
+      if (!orderedSet.has(nextValue)) {
+        ordered.push(nextValue);
+      }
+    }
+    return ordered;
+  }
+
+  function trackOptionLabels(nextOptions: DropdownOption[]) {
+    for (const option of nextOptions) {
+      knownLabels.set(option.value, option.label);
+    }
+  }
+
+  function labelForValue(nextValue: DropdownValue): string {
+    const option = resolvedOptions.find((candidate) => candidate.value === nextValue);
+    return option?.label ?? knownLabels.get(nextValue) ?? String(nextValue);
+  }
+
+  function displayLabelForValue(nextValue: DropdownValue): string {
+    const option = resolvedOptions.find((candidate) => candidate.value === nextValue) ??
+      selectedOptions.find((candidate) => candidate.value === nextValue);
+    return option ? getItemLabel(option) : labelForValue(nextValue);
+  }
+
+  // Multiselect trigger text only lists values whose label is known; values
+  // without one never render a raw fallback string into the trigger.
+  function selectedLabelTexts(nextValues: DropdownMultiValue): string[] {
+    const texts: string[] = [];
+    for (const nextValue of nextValues) {
+      const label =
+        resolvedOptions.find((candidate) => candidate.value === nextValue)?.label ??
+        knownLabels.get(nextValue);
+      if (label !== undefined) {
+        const option = resolvedOptions.find((candidate) => candidate.value === nextValue) ??
+          selectedOptions.find((candidate) => candidate.value === nextValue);
+        texts.push(option ? getItemLabel(option) : label);
+      }
+    }
+    return texts;
+  }
+
   function initialActiveValue(): DropdownValue {
-    const firstSelectedEnabled = visibleOptions.find(
-      (option) => selectedValues.includes(option.value) && !option.disabled
+    return initialActiveValueFor(visibleOptions, resolvedOptions);
+  }
+
+  function initialActiveValueFor(
+    nextVisibleOptions: DropdownOption[],
+    nextResolvedOptions: DropdownOption[]
+  ): DropdownValue {
+    const firstSelectedEnabled = nextVisibleOptions.find(
+      (option) => selectedValueSet.has(option.value) && !option.disabled
     );
-    return firstSelectedEnabled?.value ?? selectedOption?.value ?? firstEnabledOption()?.value ?? '';
+    const selectedFallback = Array.isArray(value)
+      ? undefined
+      : nextResolvedOptions.find((option) => option.value === value);
+    return firstSelectedEnabled?.value ?? selectedFallback?.value ?? nextVisibleOptions.find((option) => !option.disabled)?.value ?? '';
   }
 
   function isOptionSelected(option: DropdownOption): boolean {
-    return multiselect ? selectedValues.includes(option.value) : option.value === value;
+    return multiselect ? selectedValueSet.has(option.value) : option.value === value;
   }
 
   function activeOptionIndex(nextActiveValue: DropdownValue): number {
@@ -142,6 +267,7 @@
     const currentIndex = Math.max(0, enabledOptions.findIndex((option) => option.value === activeValue));
     const nextIndex = (currentIndex + offset + enabledOptions.length) % enabledOptions.length;
     activeValue = enabledOptions[nextIndex]?.value ?? activeValue;
+    scrollActiveOptionIntoView();
   }
 
   function clearTypeaheadBuffer() {
@@ -179,10 +305,14 @@
     });
   }
 
-  function handleTypeahead(key: string) {
-    const normalizedKey = key.startsWith('Key') && key.length === 4
+  function normalizeTypeaheadKey(key: string): string {
+    return key.startsWith('Key') && key.length === 4
       ? key.slice(3).toLocaleLowerCase()
       : key.toLocaleLowerCase();
+  }
+
+  function handleTypeahead(key: string) {
+    const normalizedKey = normalizeTypeaheadKey(key);
     const nextBuffer = `${typeaheadBuffer}${normalizedKey}`;
     const findMatch = (prefix: string) =>
       visibleOptions.find(
@@ -201,8 +331,7 @@
     }
 
     if (!open) {
-      updateResolvedPlacement();
-      open = true;
+      openMenu();
     }
     activeValue = match.value;
     scrollActiveOptionIntoView();
@@ -220,28 +349,189 @@
       } else {
         nextSelected.add(option.value);
       }
-      const nextValues = normalizeSelectedValues([...nextSelected]);
+      const nextValues = orderSelectedValues(resolvedOptions, [...nextSelected]);
       clearTypeaheadBuffer();
       void (onChange as DropdownMultiChangeHandler | undefined)?.(nextValues);
       return;
     }
 
+    if (inputMode) {
+      inputDraft = getItemLabel(option);
+      preserveInputDraftOnClose = true;
+    }
     open = false;
     clearTypeaheadBuffer();
     void (onChange as DropdownChangeHandler | undefined)?.(option.value);
     buttonElement?.focus();
   }
 
+  function clampSearchLimit(limit: number): number {
+    if (!Number.isFinite(limit)) {
+      return 10;
+    }
+    return Math.min(50, Math.max(1, Math.floor(limit)));
+  }
+
+  function clearSearchTimer() {
+    if (searchTimer !== undefined) {
+      clearTimeout(searchTimer);
+      searchTimer = undefined;
+    }
+  }
+
+  function abortSearchController() {
+    if (searchController !== undefined) {
+      searchController.abort();
+      searchController = undefined;
+    }
+  }
+
+  function scheduleSearch(query: string) {
+    clearSearchTimer();
+    searchTimer = setTimeout(() => {
+      searchTimer = undefined;
+      void runSearch(query);
+    }, Math.max(0, Math.floor(searchDebounceMs)));
+  }
+
+  async function runSearch(query: string) {
+    if (!search || loadOptions === undefined) {
+      return;
+    }
+    abortSearchController();
+    const currentRequestId = ++searchRequestId;
+    const controller = new AbortController();
+    searchController = controller;
+    searchStatus = 'loading';
+
+    try {
+      const result = await loadOptions(query, {
+        limit: clampSearchLimit(searchLimit),
+        signal: controller.signal
+      });
+      // Stale or cancelled responses must never touch the UI.
+      if (controller.signal.aborted || currentRequestId !== searchRequestId) {
+        return;
+      }
+      searchStatus = 'success';
+      applySearchResult(result ?? {}, query);
+    } catch {
+      if (controller.signal.aborted || currentRequestId !== searchRequestId) {
+        return;
+      }
+      searchOptions = [];
+      searchOptionGroups = undefined;
+      searchStatus = 'error';
+    } finally {
+      if (searchController === controller) {
+        searchController = undefined;
+      }
+    }
+  }
+
+  function mergeSelectedOptions(options: DropdownOption[]): DropdownOption[] {
+    const merged = [...options];
+    const seen = new Set(options.map((option) => option.value));
+    for (const option of selectedOptions) {
+      if (!seen.has(option.value)) {
+        merged.push(option);
+        seen.add(option.value);
+      }
+    }
+    return merged;
+  }
+
+  function applySearchResult(result: DropdownLoadOptionsResult, query = '') {
+    // optionGroups is the sole render source when present; empty groups stay hidden.
+    const groups = Array.isArray(result.optionGroups)
+      ? result.optionGroups.filter((group) => Array.isArray(group.options) && group.options.length > 0)
+      : undefined;
+    if (groups !== undefined) {
+      if (query.trim()) {
+        searchOptionGroups = groups;
+      } else {
+        const groupedOptions = groups.flatMap((group) => group.options);
+        const groupedValues = new Set(groupedOptions.map((option) => option.value));
+        const missingSelected = selectedOptions.filter((option) => !groupedValues.has(option.value));
+        searchOptionGroups = missingSelected.length ? [...groups, { options: missingSelected }] : groups;
+      }
+      searchOptions = [];
+    } else {
+      searchOptionGroups = undefined;
+      searchOptions = query.trim() ? (Array.isArray(result.options) ? result.options : []) : mergeSelectedOptions(Array.isArray(result.options) ? result.options : []);
+    }
+    // Only the first valid grouped response of an open session seeds the auto
+    // collapse state; later responses just swap groups so manual collapse and
+    // expand choices survive query refreshes within the same session.
+    if (!searchGroupsInitialized && groups !== undefined && groups.length > 0) {
+      searchGroupsInitialized = true;
+      initializeCollapsedGroups(groups);
+    }
+    const nextResolvedOptions = groups === undefined ? searchOptions : groups.flatMap((group) => group.options);
+    const nextVisibleOptions = groups === undefined
+      ? searchOptions
+      : groups.flatMap((group, groupIndex) => group.label && collapsedGroupIndexes.has(groupIndex) ? [] : group.options);
+    activeValue = initialActiveValueFor(nextVisibleOptions, nextResolvedOptions);
+    scrollActiveOptionIntoView();
+  }
+
+  function resetSearchOnClose() {
+    clearSearchTimer();
+    abortSearchController();
+    searchQuery = '';
+    if (preserveInputDraftOnClose) {
+      preserveInputDraftOnClose = false;
+    } else {
+      inputDraft = undefined;
+    }
+    searchOptions = [];
+    searchOptionGroups = undefined;
+    searchStatus = 'idle';
+  }
+
+  function beginSearchOnOpen() {
+    searchQuery = '';
+    inputDraft = undefined;
+    searchOptions = [];
+    searchOptionGroups = undefined;
+    collapsedGroupIndexes = new Set();
+    searchGroupsInitialized = false;
+    clearSearchTimer();
+    abortSearchController();
+    if (loadOptions === undefined) {
+      searchStatus = 'idle';
+      return;
+    }
+    // The empty query fires immediately on every expand.
+    void runSearch('');
+  }
+
+  function openMenu() {
+    updateResolvedPlacement();
+    if (search) {
+      beginSearchOnOpen();
+    } else {
+      initializeCollapsedGroups(renderOptionGroups);
+    }
+    open = true;
+    activeValue = initialActiveValue();
+    if (search && !inputMode) {
+      void tick().then(() => {
+        searchInputElement?.focus();
+      });
+    }
+  }
+
   function toggleOpen() {
     if (disabled) {
       return;
     }
+    clearTypeaheadBuffer();
     if (!open) {
-      updateResolvedPlacement();
-      initializeCollapsedGroups();
+      openMenu();
+      return;
     }
-    clearTypeaheadBuffer();
-    open = !open;
+    open = false;
     activeValue = initialActiveValue();
   }
 
@@ -249,19 +539,19 @@
     return collapsedGroupIndexes.has(groupIndex);
   }
 
-  function initializeCollapsedGroups() {
-    if (optionGroups === undefined || groupsCollapsedByDefault === 'false') {
+  function initializeCollapsedGroups(nextOptionGroups: DropdownOptionGroup[] | undefined) {
+    if (nextOptionGroups === undefined || groupsCollapsedByDefault === 'false') {
       collapsedGroupIndexes = new Set();
       return;
     }
     if (groupsCollapsedByDefault === 'true') {
       collapsedGroupIndexes = new Set(
-        optionGroups.flatMap((group, index) => group.label ? [index] : [])
+        nextOptionGroups.flatMap((group, index) => group.label ? [index] : [])
       );
       return;
     }
     collapsedGroupIndexes = new Set(
-      optionGroups.flatMap((group, index) =>
+      nextOptionGroups.flatMap((group, index) =>
         group.label && group.options.some((option) => isOptionSelected(option)) ? [] : group.label ? [index] : []
       )
     );
@@ -296,9 +586,7 @@
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
       if (!open) {
-        updateResolvedPlacement();
-        open = true;
-        activeValue = initialActiveValue();
+        openMenu();
       }
       moveActiveOption(event.key === 'ArrowDown' ? 1 : -1);
       return;
@@ -312,6 +600,16 @@
       !event.altKey
     ) {
       event.preventDefault();
+      if (search) {
+        const wasOpen = open;
+        if (!wasOpen) {
+          openMenu();
+        }
+        searchQuery = wasOpen ? `${searchQuery}${normalizeTypeaheadKey(event.key)}` : normalizeTypeaheadKey(event.key);
+        void onSearchChange?.(searchQuery);
+        scheduleSearch(searchQuery);
+        return;
+      }
       handleTypeahead(event.key);
       return;
     }
@@ -326,6 +624,54 @@
     }
   }
 
+  function handleSearchInput(event: Event) {
+    const nextQuery = (event.currentTarget as HTMLInputElement).value;
+    inputDraft = nextQuery;
+    if (inputMode && !multiselect && value !== '' && nextQuery !== selectedText) {
+      void (onChange as DropdownChangeHandler | undefined)?.('');
+    }
+    searchQuery = nextQuery;
+    if (inputMode) {
+      if (nextQuery.trim()) {
+        if (!open) {
+          updateResolvedPlacement();
+          open = true;
+          activeValue = initialActiveValue();
+        }
+      } else {
+        open = false;
+      }
+    }
+    void onSearchChange?.(searchQuery);
+    scheduleSearch(searchQuery);
+  }
+
+  function handleInputFocus() {
+    // 输入模式下聚焦只准备输入；用户输入有效搜索词后才展开结果。
+  }
+
+  function handleSearchKeydown(event: KeyboardEvent) {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      open = false;
+      buttonElement?.focus();
+      return;
+    }
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      moveActiveOption(event.key === 'ArrowDown' ? 1 : -1);
+      return;
+    }
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      const index = activeOptionIndex(activeValue);
+      const option = index >= 0 ? visibleOptions[index] : undefined;
+      if (option) {
+        selectOption(option);
+      }
+    }
+  }
+
   function handleFocusout(event: FocusEvent) {
     const nextTarget = event.relatedTarget;
     if (portal && nextTarget instanceof Node && menuElement?.contains(nextTarget)) {
@@ -473,6 +819,9 @@
         return;
       }
       open = false;
+      if (search) {
+        buttonElement?.focus();
+      }
     };
 
     document.addEventListener('pointerdown', handleOutsidePointer, true);
@@ -490,6 +839,8 @@
     disableOpenViewportTracking();
     disableOutsidePointerDismissal();
     clearTypeaheadBuffer();
+    clearSearchTimer();
+    abortSearchController();
   });
 </script>
 
@@ -498,6 +849,7 @@
   class={[
     'suu-dropdown',
     multiselect ? 'suu-dropdown--multiselect' : '',
+    search ? 'suu-dropdown--search' : '',
     width !== undefined || minWidth !== undefined || maxWidth !== undefined
       ? 'suu-dropdown--sized'
       : '',
@@ -509,6 +861,47 @@
   style:max-width={maxWidth}
   on:focusout={handleFocusout}
 >
+  {#if inputMode}
+    {#if multiselect && selectedValues.length > 0}
+      <div class="suu-dropdown__selected-items">
+        {#each selectedValues as selectedValue}
+          {@const selectedOption = resolvedOptions.find((option) => option.value === selectedValue) ?? selectedOptions.find((option) => option.value === selectedValue)}
+          {#if selectedOption}
+            <span class="suu-dropdown__selected-item">
+              <span>{getItemLabel(selectedOption)}</span>
+              <button
+                type="button"
+                class="suu-dropdown__selected-remove"
+                aria-label={`Remove ${getItemLabel(selectedOption)}`}
+                on:mousedown|preventDefault
+                on:click={() => selectOption(selectedOption)}
+              >×</button>
+            </span>
+          {/if}
+        {/each}
+      </div>
+    {/if}
+    <div class="suu-dropdown__input-field">
+      <input
+        bind:this={searchInputElement}
+        {id}
+        class="suu-dropdown__input"
+        type="text"
+        value={inputDisplayValue}
+        placeholder={searchPlaceholder ?? placeholder ?? ''}
+        aria-label={ariaLabel}
+        autocomplete="off"
+        role="combobox"
+        aria-expanded={open}
+        aria-autocomplete="list"
+        aria-controls={resolvedListboxId}
+        {disabled}
+        on:focus={handleInputFocus}
+        on:input={handleSearchInput}
+        on:keydown={handleSearchKeydown}
+      />
+    </div>
+  {:else}
   <button
     bind:this={buttonElement}
     {id}
@@ -522,9 +915,10 @@
     on:click={handleTriggerClick}
     on:keydown={handleKeydown}
   >
-    <span class="suu-dropdown__label">{selectedText}</span>
+    <span class="suu-dropdown__label">{selectedText || placeholder || ''}</span>
     <span class="suu-dropdown__chevron" aria-hidden="true"></span>
   </button>
+  {/if}
 
   {#if name !== undefined && !multiselect}
     <input
@@ -556,21 +950,54 @@
       style:--suu-dropdown-menu-width={portalMenuWidth}
       style:--suu-dropdown-panel-max-height={viewportPanelMaxHeight}
     >
+      {#if search && !inputMode}
+        <div class="suu-dropdown__search">
+          <svg class="suu-dropdown__search-icon" viewBox="0 0 24 24" aria-hidden="true">
+            <circle cx="11" cy="11" r="7"></circle>
+            <path d="m16 16 4 4"></path>
+          </svg>
+          <input
+            bind:this={searchInputElement}
+            class="suu-dropdown__search-input"
+            type="text"
+            value={searchQuery}
+            placeholder={searchPlaceholder ?? ''}
+            aria-label={ariaLabel}
+            autocomplete="off"
+            role="combobox"
+            aria-expanded="true"
+            aria-autocomplete="list"
+            aria-controls={resolvedListboxId}
+            on:input={handleSearchInput}
+            on:keydown={handleSearchKeydown}
+          />
+        </div>
+      {/if}
       <div
         class="suu-dropdown__panel"
+        id={resolvedListboxId}
         role="listbox"
         aria-label={ariaLabel}
         aria-multiselectable={multiselect || undefined}
       >
-        {#if optionGroups === undefined}
-          {#each options as option}
+        {#if search && searchStatus === 'loading'}
+          <div class="suu-dropdown__status suu-dropdown__status--loading" aria-live="polite">
+            <span class="suu-dropdown__spinner" aria-hidden="true"></span>
+            <span>{resolvedLoadingText}</span>
+          </div>
+        {:else if search && searchStatus === 'error'}
+          <div class="suu-dropdown__status suu-dropdown__status--error" role="alert">{resolvedErrorText}</div>
+        {:else if search && resolvedOptions.length === 0}
+          <div class="suu-dropdown__status suu-dropdown__status--empty">{resolvedNoResultsText}</div>
+        {:else if renderOptionGroups === undefined}
+          {#each renderOptions as option}
             <button
               type="button"
               class="suu-dropdown__option"
               class:suu-dropdown__option--active={option.value === activeValue}
               class:suu-dropdown__option--disabled={option.disabled}
               role="option"
-              aria-selected={multiselect ? selectedValues.includes(option.value) : option.value === value}
+              aria-selected={multiselect ? selectedValueSet.has(option.value) : option.value === value}
               aria-disabled={option.disabled}
               disabled={option.disabled}
               data-value={String(option.value)}
@@ -585,7 +1012,7 @@
               {#if multiselect}
                 <span
                   class="suu-dropdown__checkbox"
-                  data-checked={multiselect ? selectedValues.includes(option.value) : option.value === value}
+                  data-checked={multiselect ? selectedValueSet.has(option.value) : option.value === value}
                   aria-hidden="true"
                 ></span>
               {/if}
@@ -593,7 +1020,7 @@
             </button>
           {/each}
         {:else}
-          {#each optionGroups as group, groupIndex}
+          {#each renderOptionGroups as group, groupIndex}
             <div class="suu-dropdown__group" role="group" aria-label={group.label}>
               {#if group.label}
                 <button
@@ -615,7 +1042,7 @@
                   class:suu-dropdown__option--active={option.value === activeValue}
                   class:suu-dropdown__option--disabled={option.disabled}
                   role="option"
-                  aria-selected={multiselect ? selectedValues.includes(option.value) : option.value === value}
+                  aria-selected={multiselect ? selectedValueSet.has(option.value) : option.value === value}
                   aria-disabled={option.disabled}
                   disabled={option.disabled}
                   data-value={String(option.value)}
@@ -630,7 +1057,7 @@
                   {#if multiselect}
                     <span
                       class="suu-dropdown__checkbox"
-                      data-checked={multiselect ? selectedValues.includes(option.value) : option.value === value}
+                      data-checked={multiselect ? selectedValueSet.has(option.value) : option.value === value}
                       aria-hidden="true"
                     ></span>
                   {/if}