@synthaxai/ui 1.0.0 → 1.1.0

package/dist/forms/MultiSelect/MultiSelect.svelte

@@ -0,0 +1,1651 @@
+<!--
+  @component MultiSelect
+  
+  A fully accessible multi-select component with chips/tags display,
+  following WAI-ARIA 1.2 listbox pattern. Supports searchable options,
+  grouped options, and comprehensive keyboard navigation.
+  
+  Designed for healthcare applications requiring selection of multiple items
+  such as service types, diagnoses, medications, or procedures.
+  
+  @example Basic usage
+  <MultiSelect
+    label="Service Types"
+    options={serviceTypes}
+    bind:selected={selectedServices}
+    placeholder="Select services..."
+  />
+  
+  @example With search and max selections
+  <MultiSelect
+    label="Diagnoses"
+    options={diagnoses}
+    bind:selected={selectedDiagnoses}
+    searchable
+    maxSelections={5}
+    placeholder="Search diagnoses..."
+  />
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { X, ChevronDown, Check, AlertCircle, Search, Info, Loader2 } from 'lucide-svelte';
+	import { cn } from '../../utils/cn.js';
+	import { generateId, Keys } from '../../utils/keyboard.js';
+	import { announce, prefersReducedMotion } from '../../utils/accessibility.js';
+
+	// ============================================================================
+	// Types
+	// ============================================================================
+
+	type InputSize = 'sm' | 'md' | 'lg';
+
+	/**
+	 * Multi-select option item.
+	 */
+	export interface MultiSelectOption {
+		/** Unique value for the option */
+		value: string;
+		/** Display label for the option */
+		label: string;
+		/** Whether the option is disabled */
+		disabled?: boolean;
+		/** Optional description shown below the label */
+		description?: string;
+		/** Optional metadata for custom rendering */
+		metadata?: Record<string, unknown>;
+	}
+
+	/**
+	 * Grouped multi-select options.
+	 */
+	export interface MultiSelectOptionGroup {
+		/** Group label */
+		label: string;
+		/** Options in this group */
+		options: MultiSelectOption[];
+	}
+
+	type MultiSelectOptions = MultiSelectOption[] | MultiSelectOptionGroup[];
+
+	interface Props {
+		/** Unique identifier for the component */
+		id?: string;
+		/** Form field name */
+		name?: string;
+		/** Label text for the field */
+		label: string;
+		/** Currently selected options (bindable) */
+		selected?: MultiSelectOption[];
+		/** Placeholder text when no selections */
+		placeholder?: string;
+		/** Options to display (flat or grouped) */
+		options?: MultiSelectOptions;
+		/** Whether the field is required */
+		required?: boolean;
+		/** Whether the field is disabled */
+		disabled?: boolean;
+		/** Whether the field is read-only */
+		readonly?: boolean;
+		/** Error message to display */
+		error?: string;
+		/** Hint text to display below the component */
+		hint?: string;
+		/** Success message when valid */
+		successMessage?: string;
+		/** Size of the component */
+		size?: InputSize;
+		/** Whether to hide the label visually (still accessible) */
+		hideLabel?: boolean;
+		/** Additional CSS classes for the wrapper */
+		class?: string;
+		/** Enable search/filter functionality */
+		searchable?: boolean;
+		/** Search placeholder text */
+		searchPlaceholder?: string;
+		/** Maximum number of selections allowed */
+		maxSelections?: number;
+		/** Whether to close dropdown after each selection */
+		closeOnSelect?: boolean;
+		/** Show loading spinner during async operations */
+		loading?: boolean;
+		/** Message to show when no options match search */
+		emptyMessage?: string;
+		/** Whether to show "Select All" option */
+		showSelectAll?: boolean;
+		/** Label for "Select All" */
+		selectAllLabel?: string;
+		/** Whether to show selected count badge */
+		showCount?: boolean;
+		/** Custom chip rendering */
+		chipContent?: Snippet<[MultiSelectOption]>;
+		/** Custom option rendering */
+		optionContent?: Snippet<[MultiSelectOption]>;
+		/** Custom empty state content */
+		emptyContent?: Snippet;
+		/** Called when selection changes */
+		onchange?: (selected: MultiSelectOption[]) => void;
+		/** Called when an option is selected */
+		onselect?: (option: MultiSelectOption) => void;
+		/** Called when an option is deselected */
+		ondeselect?: (option: MultiSelectOption) => void;
+		/** Called when search query changes */
+		onsearch?: (query: string) => void;
+		/** Test ID for e2e testing */
+		testId?: string;
+		/** Show validation state immediately */
+		validateOnMount?: boolean;
+	}
+
+	let {
+		id = generateId('multiselect'),
+		name,
+		label,
+		selected = $bindable([]),
+		placeholder = 'Select options...',
+		options = [],
+		required = false,
+		disabled = false,
+		readonly = false,
+		error = '',
+		hint = '',
+		successMessage = '',
+		size = 'md',
+		hideLabel = false,
+		class: className = '',
+		searchable = false,
+		searchPlaceholder = 'Search...',
+		maxSelections,
+		closeOnSelect = false,
+		loading = false,
+		emptyMessage = 'No options found',
+		showSelectAll = false,
+		selectAllLabel = 'Select All',
+		showCount = true,
+		chipContent,
+		optionContent,
+		emptyContent,
+		onchange,
+		onselect,
+		ondeselect,
+		onsearch,
+		testId,
+		validateOnMount = false
+	}: Props = $props();
+
+	// ============================================================================
+	// State
+	// ============================================================================
+
+	let containerRef: HTMLDivElement | undefined = $state();
+	let inputRef: HTMLInputElement | HTMLButtonElement | undefined = $state();
+	let listboxRef: HTMLDivElement | undefined = $state();
+	let isOpen = $state(false);
+	let isFocused = $state(false);
+	let hasInteracted = $state(false);
+	let searchQuery = $state('');
+	let activeIndex = $state(-1);
+	let focusedChipIndex = $state(-1);
+
+	// ============================================================================
+	// Derived State
+	// ============================================================================
+
+	// Flatten grouped options
+	const flatOptions = $derived.by(() => {
+		if (options.length === 0) return [];
+		if ('options' in options[0]) {
+			return (options as MultiSelectOptionGroup[]).flatMap((g) => g.options);
+		}
+		return options as MultiSelectOption[];
+	});
+
+	// Check if options are grouped
+	const isGrouped = $derived(options.length > 0 && 'options' in options[0]);
+
+	// Filter options based on search
+	const filteredOptions = $derived.by(() => {
+		if (!searchable || !searchQuery.trim()) {
+			return options;
+		}
+		const query = searchQuery.toLowerCase().trim();
+		
+		if (isGrouped) {
+			const groups = options as MultiSelectOptionGroup[];
+			return groups
+				.map((group) => ({
+					...group,
+					options: group.options.filter(
+						(opt) =>
+							opt.label.toLowerCase().includes(query) ||
+							opt.description?.toLowerCase().includes(query)
+					)
+				}))
+				.filter((group) => group.options.length > 0);
+		}
+		
+		return (options as MultiSelectOption[]).filter(
+			(opt) =>
+				opt.label.toLowerCase().includes(query) ||
+				opt.description?.toLowerCase().includes(query)
+		);
+	});
+
+	// Flatten filtered options for navigation
+	const filteredFlatOptions = $derived.by(() => {
+		if (!Array.isArray(filteredOptions) || filteredOptions.length === 0) return [];
+		if ('options' in filteredOptions[0]) {
+			return (filteredOptions as MultiSelectOptionGroup[]).flatMap((g) => g.options);
+		}
+		return filteredOptions as MultiSelectOption[];
+	});
+
+	// Filter to only enabled options for navigation
+	const enabledOptions = $derived(
+		filteredFlatOptions.filter((o) => !o.disabled && !isSelected(o))
+	);
+
+	// All enabled options (including selected, for keyboard nav)
+	const allEnabledOptions = $derived(filteredFlatOptions.filter((o) => !o.disabled));
+
+	// Selected values set for quick lookup
+	const selectedValues = $derived(new Set(selected.map((o) => o.value)));
+
+	// Check if at max selections
+	const atMaxSelections = $derived(
+		maxSelections !== undefined && selected.length >= maxSelections
+	);
+
+	// Check if all options are selected
+	const allSelected = $derived(
+		flatOptions.length > 0 &&
+		flatOptions.filter((o) => !o.disabled).every((o) => selectedValues.has(o.value))
+	);
+
+	// Validation display logic
+	const shouldValidate = $derived(hasInteracted || validateOnMount);
+	const showError = $derived(shouldValidate && !!error);
+	const showSuccess = $derived(shouldValidate && !error && selected.length > 0 && !!successMessage);
+	const isValid = $derived(shouldValidate && !error && selected.length > 0 && !!successMessage);
+
+	// Show empty state
+	const showEmpty = $derived(!loading && filteredFlatOptions.length === 0);
+
+	// IDs for accessibility
+	const listboxId = $derived(`${id}-listbox`);
+	const errorId = $derived(`${id}-error`);
+	const hintId = $derived(`${id}-hint`);
+	const labelId = $derived(`${id}-label`);
+	const activeDescendantId = $derived(
+		activeIndex >= 0 ? `${id}-option-${activeIndex}` : undefined
+	);
+
+	// Build aria-describedby
+	const ariaDescribedBy = $derived(
+		[showError && errorId, hint && hintId].filter(Boolean).join(' ') || undefined
+	);
+
+	// ============================================================================
+	// Helpers
+	// ============================================================================
+
+	function isSelected(option: MultiSelectOption): boolean {
+		return selectedValues.has(option.value);
+	}
+
+	function getOptionIndex(option: MultiSelectOption): number {
+		return filteredFlatOptions.findIndex((o) => o.value === option.value);
+	}
+
+	function scrollToOption(index: number) {
+		if (!listboxRef || index < 0) return;
+		const optionEl = listboxRef.querySelector(`[data-index="${index}"]`);
+		if (optionEl && typeof optionEl.scrollIntoView === 'function') {
+			optionEl.scrollIntoView({ block: 'nearest', behavior: prefersReducedMotion() ? 'auto' : 'smooth' });
+		}
+	}
+
+	// ============================================================================
+	// Selection Logic
+	// ============================================================================
+
+	function toggleOption(option: MultiSelectOption) {
+		if (option.disabled) return;
+
+		if (isSelected(option)) {
+			// Deselect
+			selected = selected.filter((o) => o.value !== option.value);
+			announce(`Removed ${option.label}`, 'polite');
+			ondeselect?.(option);
+		} else {
+			// Check max selections
+			if (atMaxSelections) {
+				announce(`Maximum ${maxSelections} selections reached`, 'assertive');
+				return;
+			}
+			// Select
+			selected = [...selected, option];
+			announce(`Added ${option.label}`, 'polite');
+			onselect?.(option);
+		}
+
+		onchange?.(selected);
+
+		if (closeOnSelect) {
+			isOpen = false;
+			activeIndex = -1;
+		}
+	}
+
+	function removeChip(option: MultiSelectOption, e?: MouseEvent) {
+		e?.preventDefault();
+		e?.stopPropagation();
+		
+		if (disabled || readonly) return;
+
+		selected = selected.filter((o) => o.value !== option.value);
+		announce(`Removed ${option.label}`, 'polite');
+		ondeselect?.(option);
+		onchange?.(selected);
+
+		// Return focus to input
+		inputRef?.focus();
+	}
+
+	function selectAll() {
+		if (disabled || readonly) return;
+
+		if (allSelected) {
+			// Deselect all
+			selected = [];
+			announce('All options deselected', 'polite');
+		} else {
+			// Select all non-disabled options (respecting maxSelections)
+			const selectableOptions = flatOptions.filter((o) => !o.disabled);
+			if (maxSelections !== undefined) {
+				selected = selectableOptions.slice(0, maxSelections);
+				if (selectableOptions.length > maxSelections) {
+					announce(`Selected first ${maxSelections} options (maximum reached)`, 'polite');
+				} else {
+					announce('All options selected', 'polite');
+				}
+			} else {
+				selected = selectableOptions;
+				announce('All options selected', 'polite');
+			}
+		}
+		onchange?.(selected);
+	}
+
+	function clearAll() {
+		if (disabled || readonly) return;
+		selected = [];
+		announce('All selections cleared', 'polite');
+		onchange?.(selected);
+		inputRef?.focus();
+	}
+
+	// ============================================================================
+	// Event Handlers
+	// ============================================================================
+
+	function handleContainerClick(e: MouseEvent) {
+		if (disabled || readonly) return;
+		
+		// Don't open if clicking on chip remove button
+		const target = e.target as HTMLElement;
+		if (target.closest('.chip-remove')) return;
+
+		isOpen = true;
+		inputRef?.focus();
+	}
+
+	function handleInputFocus() {
+		isFocused = true;
+		focusedChipIndex = -1;
+	}
+
+	function handleInputBlur(e: FocusEvent) {
+		// Don't close if focus moves within the component
+		const relatedTarget = e.relatedTarget as HTMLElement | null;
+		if (relatedTarget && containerRef?.contains(relatedTarget)) {
+			return;
+		}
+
+		isFocused = false;
+		hasInteracted = true;
+		focusedChipIndex = -1;
+
+		// Delay closing to allow click events
+		setTimeout(() => {
+			if (!isFocused) {
+				isOpen = false;
+				activeIndex = -1;
+				searchQuery = '';
+			}
+		}, 150);
+	}
+
+	function handleSearchInput(e: Event) {
+		const target = e.target as HTMLInputElement;
+		searchQuery = target.value;
+		activeIndex = 0;
+		onsearch?.(searchQuery);
+	}
+
+	function handleKeyDown(e: KeyboardEvent) {
+		if (disabled || readonly) return;
+
+		// Handle chip navigation when not in dropdown
+		if (focusedChipIndex >= 0) {
+			handleChipKeyDown(e);
+			return;
+		}
+
+		switch (e.key) {
+			case Keys.ArrowDown:
+				e.preventDefault();
+				if (!isOpen) {
+					isOpen = true;
+					activeIndex = 0;
+				} else if (allEnabledOptions.length > 0) {
+					activeIndex = Math.min(activeIndex + 1, allEnabledOptions.length - 1);
+					const targetOption = allEnabledOptions[activeIndex];
+					const actualIndex = getOptionIndex(targetOption);
+					scrollToOption(actualIndex);
+				}
+				break;
+
+			case Keys.ArrowUp:
+				e.preventDefault();
+				if (isOpen && allEnabledOptions.length > 0) {
+					activeIndex = Math.max(activeIndex - 1, 0);
+					const targetOption = allEnabledOptions[activeIndex];
+					const actualIndex = getOptionIndex(targetOption);
+					scrollToOption(actualIndex);
+				}
+				break;
+
+		case Keys.ArrowLeft:
+			// Navigate to chips if at start of input
+			if (searchable && inputRef && inputRef instanceof HTMLInputElement && inputRef.selectionStart === 0 && selected.length > 0) {
+				e.preventDefault();
+				focusedChipIndex = selected.length - 1;
+			}
+				break;
+
+			case Keys.Home:
+				if (isOpen && allEnabledOptions.length > 0) {
+					e.preventDefault();
+					activeIndex = 0;
+					scrollToOption(getOptionIndex(allEnabledOptions[0]));
+				}
+				break;
+
+			case Keys.End:
+				if (isOpen && allEnabledOptions.length > 0) {
+					e.preventDefault();
+					activeIndex = allEnabledOptions.length - 1;
+					scrollToOption(getOptionIndex(allEnabledOptions[activeIndex]));
+				}
+				break;
+
+			case Keys.Enter:
+				if (isOpen && activeIndex >= 0 && activeIndex < allEnabledOptions.length) {
+					e.preventDefault();
+					toggleOption(allEnabledOptions[activeIndex]);
+				}
+				break;
+
+			case Keys.Space:
+				if (!searchable) {
+					e.preventDefault();
+					if (isOpen && activeIndex >= 0 && activeIndex < allEnabledOptions.length) {
+						toggleOption(allEnabledOptions[activeIndex]);
+					} else if (!isOpen) {
+						isOpen = true;
+						activeIndex = 0;
+					}
+				}
+				break;
+
+			case Keys.Escape:
+				if (isOpen) {
+					e.preventDefault();
+					isOpen = false;
+					activeIndex = -1;
+					searchQuery = '';
+				}
+				break;
+
+			case Keys.Backspace:
+				// Remove last chip if input is empty
+				if (searchable && searchQuery === '' && selected.length > 0) {
+					removeChip(selected[selected.length - 1]);
+				}
+				break;
+
+			case Keys.Tab:
+				// Close dropdown on tab
+				isOpen = false;
+				activeIndex = -1;
+				searchQuery = '';
+				break;
+		}
+	}
+
+	function handleChipKeyDown(e: KeyboardEvent) {
+		switch (e.key) {
+			case Keys.ArrowLeft:
+				e.preventDefault();
+				if (focusedChipIndex > 0) {
+					focusedChipIndex--;
+				}
+				break;
+
+			case Keys.ArrowRight:
+				e.preventDefault();
+				if (focusedChipIndex < selected.length - 1) {
+					focusedChipIndex++;
+				} else {
+					// Move focus back to input
+					focusedChipIndex = -1;
+					inputRef?.focus();
+				}
+				break;
+
+			case Keys.Backspace:
+			case Keys.Delete:
+				e.preventDefault();
+				const removedOption = selected[focusedChipIndex];
+				removeChip(removedOption);
+				// Adjust focus
+				if (selected.length === 0) {
+					focusedChipIndex = -1;
+					inputRef?.focus();
+				} else if (focusedChipIndex >= selected.length) {
+					focusedChipIndex = selected.length - 1;
+				}
+				break;
+
+			case Keys.Escape:
+				e.preventDefault();
+				focusedChipIndex = -1;
+				inputRef?.focus();
+				break;
+		}
+	}
+
+	function handleOptionClick(option: MultiSelectOption, e: MouseEvent) {
+		e.preventDefault();
+		e.stopPropagation();
+		toggleOption(option);
+		inputRef?.focus();
+	}
+
+	function handleOptionMouseEnter(index: number) {
+		const option = filteredFlatOptions[index];
+		if (!option?.disabled) {
+			const enabledIndex = allEnabledOptions.findIndex((o) => o.value === option.value);
+			if (enabledIndex >= 0) {
+				activeIndex = enabledIndex;
+			}
+		}
+	}
+
+	function handleToggleClick(e: MouseEvent) {
+		e.preventDefault();
+		e.stopPropagation();
+		if (!disabled && !readonly) {
+			isOpen = !isOpen;
+			if (isOpen) {
+				inputRef?.focus();
+			}
+		}
+	}
+
+	// ============================================================================
+	// Effects
+	// ============================================================================
+
+	// Focus chip when focusedChipIndex changes
+	$effect(() => {
+		if (focusedChipIndex >= 0 && containerRef) {
+			const chip = containerRef.querySelector(`[data-chip-index="${focusedChipIndex}"]`) as HTMLElement;
+			chip?.focus();
+		}
+	});
+</script>
+
+<div
+	class={cn(
+		'multiselect-wrapper',
+		`multiselect-${size}`,
+		disabled && 'multiselect-disabled',
+		className
+	)}
+>
+	<!-- Label -->
+	<label id={labelId} for={id} class={cn('multiselect-label', hideLabel && 'sr-only')}>
+		{label}
+		{#if required}
+			<span class="multiselect-required" aria-hidden="true">*</span>
+		{/if}
+		{#if hint && !hideLabel}
+			<span class="multiselect-hint-icon" title={hint}>
+				<Info size={14} />
+			</span>
+		{/if}
+	</label>
+
+	<!-- Main container -->
+	<div class="multiselect-container" bind:this={containerRef}>
+		<!-- Input area with chips -->
+		<!-- svelte-ignore a11y_click_events_have_key_events -->
+		<!-- svelte-ignore a11y_no_static_element_interactions -->
+		<div
+			class={cn(
+				'multiselect-input-area',
+				isFocused && 'multiselect-input-area-focused',
+				showError && 'multiselect-input-area-error',
+				isValid && 'multiselect-input-area-valid',
+				disabled && 'multiselect-input-area-disabled'
+			)}
+			onclick={handleContainerClick}
+		>
+			<!-- Selected chips -->
+			<div class="multiselect-chips">
+				{#each selected as option, index (option.value)}
+					<span
+						class={cn('multiselect-chip', focusedChipIndex === index && 'multiselect-chip-focused')}
+						data-chip-index={index}
+						tabindex={focusedChipIndex === index ? 0 : -1}
+						role="button"
+						aria-label={`${option.label}, press Delete to remove`}
+					>
+						{#if chipContent}
+							{@render chipContent(option)}
+						{:else}
+							<span class="multiselect-chip-label">{option.label}</span>
+						{/if}
+						{#if !disabled && !readonly}
+							<button
+								type="button"
+								class="chip-remove"
+								onclick={(e) => removeChip(option, e)}
+								aria-label={`Remove ${option.label}`}
+								tabindex={-1}
+							>
+								<X size={size === 'sm' ? 12 : 14} />
+							</button>
+						{/if}
+					</span>
+				{/each}
+
+				<!-- Input / Placeholder -->
+				{#if searchable}
+					<input
+						bind:this={inputRef}
+						{id}
+						{name}
+						type="text"
+						role="combobox"
+						value={searchQuery}
+						placeholder={selected.length === 0 ? placeholder : searchPlaceholder}
+						disabled={disabled}
+						readonly={readonly}
+						aria-expanded={isOpen}
+						aria-controls={listboxId}
+						aria-haspopup="listbox"
+						aria-activedescendant={activeDescendantId}
+						aria-describedby={ariaDescribedBy}
+						aria-labelledby={labelId}
+						aria-required={required}
+						aria-invalid={showError}
+						data-testid={testId}
+						class="multiselect-search-input"
+						oninput={handleSearchInput}
+						onfocus={handleInputFocus}
+						onblur={handleInputBlur}
+						onkeydown={handleKeyDown}
+					/>
+				{:else}
+					<button
+						bind:this={inputRef}
+						{id}
+						type="button"
+						role="combobox"
+						disabled={disabled}
+						aria-expanded={isOpen}
+						aria-controls={listboxId}
+						aria-haspopup="listbox"
+						aria-activedescendant={activeDescendantId}
+						aria-describedby={ariaDescribedBy}
+						aria-labelledby={labelId}
+						aria-required={required}
+						aria-invalid={showError}
+						data-testid={testId}
+						class="multiselect-trigger-button"
+						onfocus={handleInputFocus}
+						onblur={handleInputBlur}
+						onkeydown={handleKeyDown}
+					>
+						{#if selected.length === 0}
+							<span class="multiselect-placeholder">{placeholder}</span>
+						{/if}
+					</button>
+				{/if}
+			</div>
+
+			<!-- Right side controls -->
+			<div class="multiselect-controls">
+				{#if loading}
+					<span class="multiselect-loading" aria-hidden="true">
+						<Loader2 size={size === 'sm' ? 14 : 16} class="multiselect-spinner" />
+					</span>
+				{:else if showError}
+					<span class="multiselect-icon-error" aria-hidden="true">
+						<AlertCircle size={size === 'sm' ? 14 : 16} />
+					</span>
+				{:else if isValid}
+					<span class="multiselect-icon-success" aria-hidden="true">
+						<Check size={size === 'sm' ? 14 : 16} />
+					</span>
+				{/if}
+
+				{#if showCount && selected.length > 0}
+					<span class="multiselect-count" aria-label={`${selected.length} selected`}>
+						{selected.length}
+					</span>
+				{/if}
+
+				{#if selected.length > 0 && !disabled && !readonly}
+					<button
+						type="button"
+						class="multiselect-clear-button"
+						onclick={(e) => { e.stopPropagation(); clearAll(); }}
+						aria-label="Clear all selections"
+						tabindex={-1}
+					>
+						<X size={size === 'sm' ? 14 : 16} />
+					</button>
+				{/if}
+
+				<button
+					type="button"
+					class="multiselect-toggle-button"
+					onclick={handleToggleClick}
+					aria-label={isOpen ? 'Close options' : 'Open options'}
+					aria-expanded={isOpen}
+					tabindex={-1}
+					{disabled}
+				>
+					<ChevronDown
+						size={size === 'sm' ? 16 : 18}
+						class={cn('multiselect-chevron', isOpen && 'multiselect-chevron-open')}
+					/>
+				</button>
+			</div>
+		</div>
+
+		<!-- Dropdown listbox -->
+		{#if isOpen}
+			<div
+				bind:this={listboxRef}
+				id={listboxId}
+				role="listbox"
+				aria-label={`${label} options`}
+				aria-multiselectable="true"
+				class="multiselect-listbox"
+			>
+				<!-- Search indicator if searchable -->
+				{#if searchable && searchQuery}
+					<div class="multiselect-search-indicator">
+						<Search size={14} />
+						<span>Showing results for "{searchQuery}"</span>
+					</div>
+				{/if}
+
+				<!-- Select All option -->
+				{#if showSelectAll && !searchQuery && flatOptions.length > 0}
+					<!-- svelte-ignore a11y_click_events_have_key_events -->
+					<!-- svelte-ignore a11y_interactive_supports_focus -->
+					<div
+						role="option"
+						aria-selected={allSelected}
+						class={cn('multiselect-option', 'multiselect-option-select-all')}
+						onclick={() => selectAll()}
+					>
+						<span class="multiselect-option-checkbox">
+							{#if allSelected}
+								<Check size={14} />
+							{/if}
+						</span>
+						<span class="multiselect-option-label">{selectAllLabel}</span>
+						<span class="multiselect-option-count">({flatOptions.filter(o => !o.disabled).length})</span>
+					</div>
+					<div class="multiselect-divider"></div>
+				{/if}
+
+				{#if loading}
+					<div class="multiselect-loading-state" role="status" aria-live="polite">
+						<Loader2 size={20} class="multiselect-spinner" />
+						<span>Loading options...</span>
+					</div>
+				{:else if showEmpty}
+					<div class="multiselect-empty" role="status" aria-live="polite">
+						{#if emptyContent}
+							{@render emptyContent()}
+						{:else}
+							<span>{emptyMessage}</span>
+						{/if}
+					</div>
+				{:else if isGrouped}
+					{#each filteredOptions as group, groupIndex}
+						{@const typedGroup = group as MultiSelectOptionGroup}
+						<div class="multiselect-group" role="group" aria-labelledby={`${id}-group-${groupIndex}`}>
+							<div id={`${id}-group-${groupIndex}`} class="multiselect-group-label">
+								{typedGroup.label}
+							</div>
+							{#each typedGroup.options as option}
+								{@const optionIndex = getOptionIndex(option)}
+								{@const enabledIndex = allEnabledOptions.findIndex((o) => o.value === option.value)}
+								{@const isActive = enabledIndex === activeIndex}
+								{@const selected = isSelected(option)}
+								{@const isDisabled = option.disabled || (!selected && atMaxSelections)}
+								<!-- svelte-ignore a11y_interactive_supports_focus -->
+								<!-- svelte-ignore a11y_click_events_have_key_events -->
+								<div
+									id={`${id}-option-${optionIndex}`}
+									role="option"
+									aria-selected={selected}
+									aria-disabled={isDisabled}
+									data-index={optionIndex}
+									class={cn(
+										'multiselect-option',
+										isActive && 'multiselect-option-active',
+										selected && 'multiselect-option-selected',
+										isDisabled && 'multiselect-option-disabled'
+									)}
+									onclick={(e) => !isDisabled && handleOptionClick(option, e)}
+									onmouseenter={() => handleOptionMouseEnter(optionIndex)}
+								>
+									<span class="multiselect-option-checkbox">
+										{#if selected}
+											<Check size={14} />
+										{/if}
+									</span>
+									{#if optionContent}
+										{@render optionContent(option)}
+									{:else}
+										<div class="multiselect-option-content">
+											<span class="multiselect-option-label">{option.label}</span>
+											{#if option.description}
+												<span class="multiselect-option-description">{option.description}</span>
+											{/if}
+										</div>
+									{/if}
+								</div>
+							{/each}
+						</div>
+					{/each}
+				{:else}
+					{#each filteredFlatOptions as option, index}
+						{@const enabledIndex = allEnabledOptions.findIndex((o) => o.value === option.value)}
+						{@const isActive = enabledIndex === activeIndex}
+						{@const selected = isSelected(option)}
+						{@const isDisabled = option.disabled || (!selected && atMaxSelections)}
+						<!-- svelte-ignore a11y_interactive_supports_focus -->
+						<!-- svelte-ignore a11y_click_events_have_key_events -->
+						<div
+							id={`${id}-option-${index}`}
+							role="option"
+							aria-selected={selected}
+							aria-disabled={isDisabled}
+							data-index={index}
+							class={cn(
+								'multiselect-option',
+								isActive && 'multiselect-option-active',
+								selected && 'multiselect-option-selected',
+								isDisabled && 'multiselect-option-disabled'
+							)}
+							onclick={(e) => !isDisabled && handleOptionClick(option, e)}
+							onmouseenter={() => handleOptionMouseEnter(index)}
+						>
+							<span class="multiselect-option-checkbox">
+								{#if selected}
+									<Check size={14} />
+								{/if}
+							</span>
+							{#if optionContent}
+								{@render optionContent(option)}
+							{:else}
+								<div class="multiselect-option-content">
+									<span class="multiselect-option-label">{option.label}</span>
+									{#if option.description}
+										<span class="multiselect-option-description">{option.description}</span>
+									{/if}
+								</div>
+							{/if}
+						</div>
+					{/each}
+				{/if}
+
+				{#if maxSelections !== undefined && !showEmpty}
+					<div class="multiselect-max-info">
+						{selected.length} / {maxSelections} selected
+					</div>
+				{/if}
+			</div>
+		{/if}
+	</div>
+
+	<!-- Screen reader announcements -->
+	{#if isOpen && !loading && filteredFlatOptions.length > 0}
+		<div class="sr-only" role="status" aria-live="polite" aria-atomic="true">
+			{filteredFlatOptions.length} option{filteredFlatOptions.length === 1 ? '' : 's'} available,
+			{selected.length} selected
+		</div>
+	{/if}
+
+	<!-- Footer messages -->
+	<div class="multiselect-footer">
+		{#if showError}
+			<p id={errorId} class="multiselect-message multiselect-message-error" role="alert" aria-live="assertive">
+				{error}
+			</p>
+		{:else if showSuccess}
+			<p class="multiselect-message multiselect-message-success">
+				{successMessage}
+			</p>
+		{:else if hint && isFocused}
+			<p id={hintId} class="multiselect-message multiselect-message-hint">
+				{hint}
+			</p>
+		{/if}
+	</div>
+</div>
+
+<style>
+	/* ========================================
+	   BASE WRAPPER
+	   ======================================== */
+	.multiselect-wrapper {
+		display: flex;
+		flex-direction: column;
+		gap: 0.375rem;
+		position: relative;
+	}
+
+	.multiselect-disabled {
+		opacity: 0.6;
+	}
+
+	/* ========================================
+	   LABEL
+	   ======================================== */
+	.multiselect-label {
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+		font-weight: 500;
+		color: var(--ui-text-primary);
+	}
+
+	.multiselect-sm .multiselect-label {
+		font-size: 0.75rem;
+	}
+
+	.multiselect-md .multiselect-label,
+	.multiselect-lg .multiselect-label {
+		font-size: 0.875rem;
+	}
+
+	.multiselect-required {
+		color: rgb(var(--ui-color-error));
+	}
+
+	:global([data-theme='dark']) .multiselect-required {
+		color: rgb(var(--ui-color-error-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-required {
+			color: rgb(var(--ui-color-error-light));
+		}
+	}
+
+	.multiselect-hint-icon {
+		color: var(--ui-text-tertiary);
+		cursor: help;
+	}
+
+	/* ========================================
+	   CONTAINER
+	   ======================================== */
+	.multiselect-container {
+		position: relative;
+	}
+
+	/* ========================================
+	   INPUT AREA
+	   ======================================== */
+	.multiselect-input-area {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		min-height: 2.5rem;
+		padding: 0.375rem 0.5rem;
+		border: 2px solid var(--ui-border-default);
+		border-radius: 0.5rem;
+		background: var(--ui-bg-secondary);
+		cursor: pointer;
+		transition: all 0.2s ease;
+	}
+
+	.multiselect-sm .multiselect-input-area {
+		min-height: 2rem;
+		padding: 0.25rem 0.375rem;
+	}
+
+	.multiselect-lg .multiselect-input-area {
+		min-height: 3rem;
+		padding: 0.5rem 0.625rem;
+	}
+
+	.multiselect-input-area-focused {
+		outline: none;
+		background: var(--ui-bg-primary);
+		border-color: rgb(var(--ui-color-primary));
+		box-shadow: 0 0 0 3px rgb(var(--ui-color-primary) / 0.4);
+	}
+
+	:global([data-theme='dark']) .multiselect-input-area-focused {
+		border-color: rgb(var(--ui-color-primary-light));
+		box-shadow: 0 0 0 3px rgb(var(--ui-color-primary-light) / 0.5);
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-input-area-focused {
+			border-color: rgb(var(--ui-color-primary-light));
+			box-shadow: 0 0 0 3px rgb(var(--ui-color-primary-light) / 0.5);
+		}
+	}
+
+	.multiselect-input-area-disabled {
+		cursor: not-allowed;
+		background: var(--ui-bg-tertiary);
+	}
+
+	.multiselect-input-area-error {
+		border-color: rgb(var(--ui-color-error));
+	}
+
+	:global([data-theme='dark']) .multiselect-input-area-error {
+		border-color: rgb(var(--ui-color-error-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-input-area-error {
+			border-color: rgb(var(--ui-color-error-light));
+		}
+	}
+
+	.multiselect-input-area-valid {
+		border-color: rgb(var(--ui-color-success));
+	}
+
+	:global([data-theme='dark']) .multiselect-input-area-valid {
+		border-color: rgb(var(--ui-color-success-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-input-area-valid {
+			border-color: rgb(var(--ui-color-success-light));
+		}
+	}
+
+	/* ========================================
+	   CHIPS
+	   ======================================== */
+	.multiselect-chips {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.375rem;
+		flex: 1;
+		min-width: 0;
+		align-items: center;
+	}
+
+	.multiselect-chip {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.25rem;
+		padding: 0.125rem 0.375rem 0.125rem 0.5rem;
+		background: rgb(var(--ui-color-primary) / 0.1);
+		color: rgb(var(--ui-color-primary));
+		border-radius: 9999px;
+		font-size: 0.8125rem;
+		font-weight: 500;
+		max-width: 200px;
+		transition: all 0.15s ease;
+	}
+
+	:global([data-theme='dark']) .multiselect-chip {
+		background: rgb(var(--ui-color-primary-light) / 0.15);
+		color: rgb(var(--ui-color-primary-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-chip {
+			background: rgb(var(--ui-color-primary-light) / 0.15);
+			color: rgb(var(--ui-color-primary-light));
+		}
+	}
+
+	.multiselect-sm .multiselect-chip {
+		font-size: 0.75rem;
+		padding: 0.0625rem 0.25rem 0.0625rem 0.375rem;
+	}
+
+	.multiselect-chip-focused {
+		outline: 2px solid rgb(var(--ui-color-primary));
+		outline-offset: 1px;
+	}
+
+	:global([data-theme='dark']) .multiselect-chip-focused {
+		outline-color: rgb(var(--ui-color-primary-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-chip-focused {
+			outline-color: rgb(var(--ui-color-primary-light));
+		}
+	}
+
+	.multiselect-chip-label {
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.chip-remove {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: 0.125rem;
+		background: transparent;
+		border: none;
+		color: inherit;
+		cursor: pointer;
+		border-radius: 50%;
+		opacity: 0.7;
+		transition: all 0.15s ease;
+	}
+
+	.chip-remove:hover {
+		opacity: 1;
+		background: rgb(var(--ui-color-primary) / 0.2);
+	}
+
+	:global([data-theme='dark']) .chip-remove:hover {
+		background: rgb(var(--ui-color-primary-light) / 0.25);
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .chip-remove:hover {
+			background: rgb(var(--ui-color-primary-light) / 0.25);
+		}
+	}
+
+	/* ========================================
+	   SEARCH INPUT
+	   ======================================== */
+	.multiselect-search-input {
+		flex: 1;
+		min-width: 60px;
+		border: none;
+		background: transparent;
+		color: var(--ui-text-primary);
+		font-size: 0.875rem;
+		outline: none;
+	}
+
+	.multiselect-search-input::placeholder {
+		color: var(--ui-text-tertiary);
+	}
+
+	.multiselect-sm .multiselect-search-input {
+		font-size: 0.8125rem;
+	}
+
+	.multiselect-lg .multiselect-search-input {
+		font-size: 1rem;
+	}
+
+	.multiselect-trigger-button {
+		flex: 1;
+		min-width: 0;
+		border: none;
+		background: transparent;
+		color: var(--ui-text-primary);
+		font-size: 0.875rem;
+		text-align: left;
+		cursor: pointer;
+		outline: none;
+	}
+
+	.multiselect-placeholder {
+		color: var(--ui-text-tertiary);
+	}
+
+	/* ========================================
+	   CONTROLS
+	   ======================================== */
+	.multiselect-controls {
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+		flex-shrink: 0;
+	}
+
+	.multiselect-loading,
+	.multiselect-icon-error,
+	.multiselect-icon-success {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		color: var(--ui-text-tertiary);
+	}
+
+	.multiselect-icon-error {
+		color: rgb(var(--ui-color-error));
+	}
+
+	:global([data-theme='dark']) .multiselect-icon-error {
+		color: rgb(var(--ui-color-error-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-icon-error {
+			color: rgb(var(--ui-color-error-light));
+		}
+	}
+
+	.multiselect-icon-success {
+		color: rgb(var(--ui-color-success));
+	}
+
+	:global([data-theme='dark']) .multiselect-icon-success {
+		color: rgb(var(--ui-color-success-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-icon-success {
+			color: rgb(var(--ui-color-success-light));
+		}
+	}
+
+	.multiselect-spinner {
+		animation: spin 1s linear infinite;
+	}
+
+	@keyframes spin {
+		from { transform: rotate(0deg); }
+		to { transform: rotate(360deg); }
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.multiselect-spinner {
+			animation: none;
+		}
+	}
+
+	.multiselect-count {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		min-width: 1.25rem;
+		height: 1.25rem;
+		padding: 0 0.375rem;
+		background: rgb(var(--ui-color-primary));
+		color: white;
+		font-size: 0.6875rem;
+		font-weight: 600;
+		border-radius: 9999px;
+	}
+
+	:global([data-theme='dark']) .multiselect-count {
+		background: rgb(var(--ui-color-primary-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-count {
+			background: rgb(var(--ui-color-primary-light));
+		}
+	}
+
+	.multiselect-clear-button,
+	.multiselect-toggle-button {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: 0.25rem;
+		border: none;
+		background: transparent;
+		color: var(--ui-text-tertiary);
+		cursor: pointer;
+		border-radius: 0.25rem;
+		transition: all 0.15s ease;
+	}
+
+	.multiselect-clear-button:hover,
+	.multiselect-toggle-button:hover {
+		color: var(--ui-text-primary);
+		background: var(--ui-bg-tertiary);
+	}
+
+	.multiselect-toggle-button:disabled {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
+
+	.multiselect-chevron {
+		transition: transform 0.2s ease;
+	}
+
+	.multiselect-chevron-open {
+		transform: rotate(180deg);
+	}
+
+	/* ========================================
+	   LISTBOX DROPDOWN
+	   ======================================== */
+	.multiselect-listbox {
+		position: absolute;
+		top: 100%;
+		left: 0;
+		right: 0;
+		z-index: 50;
+		margin-top: 0.25rem;
+		max-height: 18rem;
+		overflow-y: auto;
+		background: var(--ui-bg-primary);
+		border: 2px solid var(--ui-border-default);
+		border-radius: 0.5rem;
+		box-shadow: var(--ui-shadow-lg);
+		animation: slideDown 0.15s ease-out;
+	}
+
+	@keyframes slideDown {
+		from {
+			opacity: 0;
+			transform: translateY(-4px);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0);
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.multiselect-listbox {
+			animation: none;
+		}
+	}
+
+	/* ========================================
+	   SEARCH INDICATOR
+	   ======================================== */
+	.multiselect-search-indicator {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		padding: 0.5rem 0.75rem;
+		font-size: 0.75rem;
+		color: var(--ui-text-tertiary);
+		background: var(--ui-bg-secondary);
+		border-bottom: 1px solid var(--ui-border-default);
+	}
+
+	/* ========================================
+	   OPTIONS
+	   ======================================== */
+	.multiselect-option {
+		display: flex;
+		align-items: flex-start;
+		gap: 0.5rem;
+		padding: 0.625rem 0.75rem;
+		cursor: pointer;
+		transition: background-color 0.1s ease;
+	}
+
+	.multiselect-option:hover,
+	.multiselect-option-active {
+		background: var(--ui-bg-secondary);
+	}
+
+	.multiselect-option-selected {
+		background: rgb(var(--ui-color-primary) / 0.08);
+	}
+
+	:global([data-theme='dark']) .multiselect-option-selected {
+		background: rgb(var(--ui-color-primary-light) / 0.12);
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-option-selected {
+			background: rgb(var(--ui-color-primary-light) / 0.12);
+		}
+	}
+
+	.multiselect-option-active.multiselect-option-selected {
+		background: rgb(var(--ui-color-primary) / 0.12);
+	}
+
+	:global([data-theme='dark']) .multiselect-option-active.multiselect-option-selected {
+		background: rgb(var(--ui-color-primary-light) / 0.18);
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-option-active.multiselect-option-selected {
+			background: rgb(var(--ui-color-primary-light) / 0.18);
+		}
+	}
+
+	.multiselect-option-disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+
+	.multiselect-option-disabled:hover {
+		background: transparent;
+	}
+
+	.multiselect-option-select-all {
+		font-weight: 500;
+	}
+
+	.multiselect-option-checkbox {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 1.125rem;
+		height: 1.125rem;
+		border: 2px solid var(--ui-border-default);
+		border-radius: 0.25rem;
+		flex-shrink: 0;
+		background: var(--ui-bg-primary);
+		color: white;
+		transition: all 0.15s ease;
+	}
+
+	.multiselect-option-selected .multiselect-option-checkbox {
+		background: rgb(var(--ui-color-primary));
+		border-color: rgb(var(--ui-color-primary));
+	}
+
+	:global([data-theme='dark']) .multiselect-option-selected .multiselect-option-checkbox {
+		background: rgb(var(--ui-color-primary-light));
+		border-color: rgb(var(--ui-color-primary-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-option-selected .multiselect-option-checkbox {
+			background: rgb(var(--ui-color-primary-light));
+			border-color: rgb(var(--ui-color-primary-light));
+		}
+	}
+
+	.multiselect-option-content {
+		display: flex;
+		flex-direction: column;
+		gap: 0.125rem;
+		min-width: 0;
+		flex: 1;
+	}
+
+	.multiselect-option-label {
+		font-weight: 500;
+		color: var(--ui-text-primary);
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+
+	.multiselect-option-description {
+		font-size: 0.75rem;
+		color: var(--ui-text-tertiary);
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+
+	.multiselect-option-count {
+		font-size: 0.75rem;
+		color: var(--ui-text-tertiary);
+		margin-left: auto;
+	}
+
+	/* ========================================
+	   GROUPS
+	   ======================================== */
+	.multiselect-group {
+		padding-top: 0.25rem;
+	}
+
+	.multiselect-group:not(:first-child) {
+		border-top: 1px solid var(--ui-border-default);
+		margin-top: 0.25rem;
+	}
+
+	.multiselect-group-label {
+		padding: 0.5rem 0.75rem 0.25rem;
+		font-size: 0.6875rem;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		color: var(--ui-text-tertiary);
+	}
+
+	/* ========================================
+	   DIVIDER
+	   ======================================== */
+	.multiselect-divider {
+		height: 1px;
+		background: var(--ui-border-default);
+		margin: 0.25rem 0;
+	}
+
+	/* ========================================
+	   STATES
+	   ======================================== */
+	.multiselect-loading-state,
+	.multiselect-empty {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		gap: 0.5rem;
+		padding: 1.5rem;
+		color: var(--ui-text-tertiary);
+		font-size: 0.875rem;
+	}
+
+	.multiselect-max-info {
+		padding: 0.5rem 0.75rem;
+		font-size: 0.75rem;
+		color: var(--ui-text-tertiary);
+		text-align: center;
+		background: var(--ui-bg-secondary);
+		border-top: 1px solid var(--ui-border-default);
+	}
+
+	/* ========================================
+	   FOOTER & MESSAGES
+	   ======================================== */
+	.multiselect-footer {
+		min-height: 1.25rem;
+	}
+
+	.multiselect-message {
+		font-size: 0.75rem;
+		animation: slideIn 0.2s ease-out;
+	}
+
+	@keyframes slideIn {
+		from {
+			opacity: 0;
+			transform: translateY(-4px);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0);
+		}
+	}
+
+	.multiselect-message-error {
+		color: rgb(var(--ui-color-error));
+	}
+
+	:global([data-theme='dark']) .multiselect-message-error {
+		color: rgb(var(--ui-color-error-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-message-error {
+			color: rgb(var(--ui-color-error-light));
+		}
+	}
+
+	.multiselect-message-success {
+		color: rgb(var(--ui-color-success));
+	}
+
+	:global([data-theme='dark']) .multiselect-message-success {
+		color: rgb(var(--ui-color-success-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .multiselect-message-success {
+			color: rgb(var(--ui-color-success-light));
+		}
+	}
+
+	.multiselect-message-hint {
+		color: var(--ui-text-tertiary);
+	}
+
+	/* ========================================
+	   UTILITIES
+	   ======================================== */
+	.sr-only {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+		border: 0;
+	}
+</style>