@thangnqdev/ui 0.2.1 → 0.2.3

package/src/forms/Combobox.tsx

@@ -1,512 +1,512 @@
-import React, { forwardRef, useState, useRef, useEffect, useId } from 'react';
-import { Check, ChevronsUpDown, Search, X } from 'lucide-react';
-import { cn } from '../utils/cn';
-import { Popover } from '../overlays/Popover';
-import { Chip } from '../data-display/Chip';
-
-export interface ComboboxOption {
-  value: string;
-  label: string;
-  description?: string;
-  icon?: React.ReactNode;
-  disabled?: boolean;
-}
-
-export interface ComboboxProps {
-  options: ComboboxOption[];
-  value?: string;
-  defaultValue?: string;
-  onChange?: (val: string) => void;
-  placeholder?: string;
-  searchPlaceholder?: string;
-  emptyText?: string;
-  disabled?: boolean;
-  clearable?: boolean;
-  className?: string;
-  name?: string;
-  id?: string;
-  'aria-label'?: string;
-}
-
-export const Combobox = forwardRef<HTMLDivElement, ComboboxProps>(
-  (
-    {
-      options,
-      value: controlledVal,
-      defaultValue = '',
-      onChange,
-      placeholder = 'Select option...',
-      searchPlaceholder = 'Search items...',
-      emptyText = 'No items found.',
-      disabled = false,
-      clearable = true,
-      className,
-      name,
-      id: customId,
-      'aria-label': ariaLabel = 'Select option',
-    },
-    ref
-  ) => {
-    const baseId = useId();
-    const comboId = customId || `combobox-${baseId}`;
-    const listboxId = `listbox-${baseId}`;
-
-    const [internalVal, setInternalVal] = useState(defaultValue);
-    const isControlled = controlledVal !== undefined;
-    const selectedValue = isControlled ? controlledVal : internalVal;
-
-    const [search, setSearch] = useState('');
-    const [isOpen, setIsOpen] = useState(false);
-    const [highlightIndex, setHighlightIndex] = useState(0);
-
-    const searchInputRef = useRef<HTMLInputElement>(null);
-    const triggerRef = useRef<HTMLButtonElement>(null);
-
-    const filteredOptions = options.filter(
-      (opt) =>
-        opt.label.toLowerCase().includes(search.toLowerCase()) ||
-        opt.value.toLowerCase().includes(search.toLowerCase()) ||
-        (opt.description && opt.description.toLowerCase().includes(search.toLowerCase()))
-    );
-
-    const selectedOption = options.find((opt) => opt.value === selectedValue);
-
-    // Keep highlight index valid
-    useEffect(() => {
-      if (filteredOptions.length > 0) {
-        setHighlightIndex((prev) => Math.min(prev, filteredOptions.length - 1));
-      }
-    }, [filteredOptions.length]);
-
-    const handleSelect = (val: string) => {
-      if (!isControlled) {
-        setInternalVal(val);
-      }
-      onChange?.(val);
-      setIsOpen(false);
-      setSearch('');
-      triggerRef.current?.focus();
-    };
-
-    const handleClear = (e: React.MouseEvent) => {
-      e.stopPropagation();
-      if (!isControlled) {
-        setInternalVal('');
-      }
-      onChange?.('');
-    };
-
-    const handleKeyDown = (e: React.KeyboardEvent) => {
-      if (!isOpen) {
-        if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
-          e.preventDefault();
-          setIsOpen(true);
-        }
-        return;
-      }
-
-      if (e.key === 'ArrowDown') {
-        e.preventDefault();
-        let next = highlightIndex + 1;
-        while (next < filteredOptions.length && filteredOptions[next]?.disabled) {
-          next++;
-        }
-        if (next < filteredOptions.length) {
-          setHighlightIndex(next);
-        }
-      } else if (e.key === 'ArrowUp') {
-        e.preventDefault();
-        let prev = highlightIndex - 1;
-        while (prev >= 0 && filteredOptions[prev]?.disabled) {
-          prev--;
-        }
-        if (prev >= 0) {
-          setHighlightIndex(prev);
-        }
-      } else if (e.key === 'Home') {
-        e.preventDefault();
-        let first = 0;
-        while (first < filteredOptions.length && filteredOptions[first]?.disabled) {
-          first++;
-        }
-        setHighlightIndex(first);
-      } else if (e.key === 'End') {
-        e.preventDefault();
-        let last = filteredOptions.length - 1;
-        while (last >= 0 && filteredOptions[last]?.disabled) {
-          last--;
-        }
-        setHighlightIndex(last);
-      } else if (e.key === 'Enter') {
-        e.preventDefault();
-        const highlighted = filteredOptions[highlightIndex];
-        if (highlighted && !highlighted.disabled) {
-          handleSelect(highlighted.value);
-        }
-      } else if (e.key === 'Escape') {
-        e.preventDefault();
-        setIsOpen(false);
-        triggerRef.current?.focus();
-      }
-    };
-
-    const activeDescendantId =
-      filteredOptions[highlightIndex]
-        ? `combobox-opt-${baseId}-${filteredOptions[highlightIndex].value}`
-        : undefined;
-
-    return (
-      <div ref={ref} className={cn('relative w-full', className)}>
-        {name && <input type="hidden" name={name} value={selectedValue} />}
-        <Popover
-          isOpen={isOpen}
-          onClose={() => setIsOpen(false)}
-          trigger={
-            <button
-              ref={triggerRef}
-              id={comboId}
-              type="button"
-              disabled={disabled}
-              role="combobox"
-              aria-expanded={isOpen}
-              aria-haspopup="listbox"
-              aria-controls={isOpen ? listboxId : undefined}
-              aria-label={ariaLabel}
-              onClick={() => !disabled && setIsOpen(!isOpen)}
-              onKeyDown={handleKeyDown}
-              className={cn(
-                'w-full h-10 px-3.5 rounded-[var(--ui-radius-md)] border bg-[var(--ui-bg-surface)] text-left flex items-center justify-between text-sm transition-all shadow-inner cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ui-primary)]',
-                disabled
-                  ? 'opacity-50 cursor-not-allowed border-[var(--ui-border-subtle)]'
-                  : 'border-[var(--ui-border-default)] hover:border-[var(--ui-border-strong)]'
-              )}
-            >
-              <div className="flex items-center gap-2.5 truncate">
-                {selectedOption?.icon}
-                <span className={selectedOption ? 'text-[var(--ui-text-primary)] font-medium' : 'text-[var(--ui-text-muted)]'}>
-                  {selectedOption ? selectedOption.label : placeholder}
-                </span>
-              </div>
-
-              <div className="flex items-center gap-1 text-[var(--ui-text-muted)]">
-                {clearable && selectedValue && !disabled && (
-                  <span
-                    onClick={handleClear}
-                    className="p-1 rounded-full hover:bg-[var(--ui-bg-tertiary)] hover:text-[var(--ui-text-primary)] transition-colors cursor-pointer"
-                  >
-                    <X className="w-3.5 h-3.5" />
-                  </span>
-                )}
-                <ChevronsUpDown className="w-4 h-4 opacity-50 shrink-0" />
-              </div>
-            </button>
-          }
-        >
-          <div className="p-2 w-72 rounded-2xl bg-[var(--ui-bg-surface)] backdrop-blur-2xl border border-[var(--ui-border-default)] shadow-2xl space-y-2">
-            <div className="relative flex items-center">
-              <Search className="absolute left-2.5 w-3.5 h-3.5 text-[var(--ui-text-muted)] pointer-events-none" />
-              <input
-                ref={searchInputRef}
-                type="text"
-                autoFocus
-                placeholder={searchPlaceholder}
-                value={search}
-                onChange={(e) => {
-                  setSearch(e.target.value);
-                  setHighlightIndex(0);
-                }}
-                onKeyDown={handleKeyDown}
-                role="combobox"
-                aria-autocomplete="list"
-                aria-expanded="true"
-                aria-controls={listboxId}
-                aria-activedescendant={activeDescendantId}
-                className="w-full h-8 pl-8 pr-3 text-xs rounded-xl bg-[var(--ui-bg-secondary)] border border-[var(--ui-border-subtle)] focus:outline-none focus:border-[var(--ui-primary)] text-[var(--ui-text-primary)] placeholder:text-[var(--ui-text-muted)]"
-              />
-            </div>
-
-            <div id={listboxId} className="max-h-56 overflow-y-auto space-y-0.5" role="listbox">
-              {filteredOptions.length === 0 ? (
-                <div className="py-4 text-center text-xs text-[var(--ui-text-muted)]">{emptyText}</div>
-              ) : (
-                filteredOptions.map((opt, idx) => {
-                  const isSelected = opt.value === selectedValue;
-                  const isHighlighted = idx === highlightIndex;
-                  const optId = `combobox-opt-${baseId}-${opt.value}`;
-
-                  return (
-                    <div
-                      key={opt.value}
-                      id={optId}
-                      role="option"
-                      aria-selected={isSelected}
-                      aria-disabled={opt.disabled}
-                      onClick={() => !opt.disabled && handleSelect(opt.value)}
-                      onMouseEnter={() => !opt.disabled && setHighlightIndex(idx)}
-                      className={cn(
-                        'flex items-center justify-between px-3 py-2 rounded-xl text-xs font-medium cursor-pointer transition-colors select-none',
-                        opt.disabled && 'opacity-40 cursor-not-allowed pointer-events-none',
-                        isSelected
-                          ? 'bg-[var(--ui-primary)] text-white font-semibold shadow-xs'
-                          : isHighlighted
-                          ? 'bg-[var(--ui-bg-tertiary)] text-[var(--ui-text-primary)]'
-                          : 'text-[var(--ui-text-primary)]'
-                      )}
-                    >
-                      <div className="flex items-center gap-2 truncate">
-                        {opt.icon}
-                        <div>
-                          <span className="block truncate">{opt.label}</span>
-                          {opt.description && (
-                            <span className={cn('text-[10px] block truncate', isSelected ? 'text-white/80' : 'text-[var(--ui-text-muted)]')}>
-                              {opt.description}
-                            </span>
-                          )}
-                        </div>
-                      </div>
-
-                      {isSelected && <Check className="w-3.5 h-3.5 shrink-0" />}
-                    </div>
-                  );
-                })
-              )}
-            </div>
-          </div>
-        </Popover>
-      </div>
-    );
-  }
-);
-Combobox.displayName = 'Combobox';
-
-/* -------------------------------------------------------------------------------------------------
- * MultiSelect Component
- * -----------------------------------------------------------------------------------------------*/
-export interface MultiSelectProps {
-  options: ComboboxOption[];
-  value?: string[];
-  defaultValue?: string[];
-  onChange?: (val: string[]) => void;
-  placeholder?: string;
-  searchPlaceholder?: string;
-  maxCount?: number;
-  disabled?: boolean;
-  className?: string;
-}
-
-export const MultiSelect = forwardRef<HTMLDivElement, MultiSelectProps>(
-  (
-    {
-      options,
-      value: controlledVal,
-      defaultValue = [],
-      onChange,
-      placeholder = 'Select items...',
-      searchPlaceholder = 'Search options...',
-      maxCount = 3,
-      disabled = false,
-      className,
-    },
-    ref
-  ) => {
-    const [internalVal, setInternalVal] = useState<string[]>(defaultValue);
-    const isControlled = controlledVal !== undefined;
-    const selectedValues = isControlled ? controlledVal : internalVal;
-
-    const [search, setSearch] = useState('');
-    const [isOpen, setIsOpen] = useState(false);
-    const [highlightedIndex, setHighlightedIndex] = useState(0);
-
-    const filteredOptions = options.filter(
-      (opt) =>
-        opt.label.toLowerCase().includes(search.toLowerCase()) ||
-        opt.value.toLowerCase().includes(search.toLowerCase())
-    );
-
-    const toggleOption = (val: string) => {
-      const opt = options.find((o) => o.value === val);
-      if (opt?.disabled) return;
-
-      const next = selectedValues.includes(val)
-        ? selectedValues.filter((v) => v !== val)
-        : [...selectedValues, val];
-      if (!isControlled) {
-        setInternalVal(next);
-      }
-      onChange?.(next);
-    };
-
-    const removeTag = (val: string, e?: React.MouseEvent) => {
-      e?.stopPropagation?.();
-      const next = selectedValues.filter((v) => v !== val);
-      if (!isControlled) {
-        setInternalVal(next);
-      }
-      onChange?.(next);
-    };
-
-    const clearAll = (e?: React.MouseEvent) => {
-      e?.stopPropagation?.();
-      if (!isControlled) {
-        setInternalVal([]);
-      }
-      onChange?.([]);
-    };
-
-    const handleSearchKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
-      if (filteredOptions.length === 0) return;
-
-      if (e.key === 'ArrowDown') {
-        e.preventDefault();
-        setHighlightedIndex((prev) => {
-          let next = (prev + 1) % filteredOptions.length;
-          while (filteredOptions[next]?.disabled && next !== prev) {
-            next = (next + 1) % filteredOptions.length;
-          }
-          return next;
-        });
-      } else if (e.key === 'ArrowUp') {
-        e.preventDefault();
-        setHighlightedIndex((prev) => {
-          let next = (prev - 1 + filteredOptions.length) % filteredOptions.length;
-          while (filteredOptions[next]?.disabled && next !== prev) {
-            next = (next - 1 + filteredOptions.length) % filteredOptions.length;
-          }
-          return next;
-        });
-      } else if (e.key === 'Enter' || e.key === ' ') {
-        e.preventDefault();
-        const current = filteredOptions[highlightedIndex];
-        if (current && !current.disabled) {
-          toggleOption(current.value);
-        }
-      } else if (e.key === 'Escape') {
-        e.preventDefault();
-        setIsOpen(false);
-      }
-    };
-
-    return (
-      <div ref={ref} className={cn('relative w-full', className)}>
-        <Popover
-          isOpen={isOpen}
-          onClose={() => setIsOpen(false)}
-          trigger={
-            <div
-              tabIndex={disabled ? -1 : 0}
-              role="combobox"
-              aria-expanded={isOpen}
-              aria-haspopup="listbox"
-              onClick={() => !disabled && setIsOpen(!isOpen)}
-              onKeyDown={(e) => {
-                if ((e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') && !disabled) {
-                  e.preventDefault();
-                  setIsOpen(true);
-                }
-              }}
-              className={cn(
-                'min-h-10 py-1.5 px-3 rounded-[var(--ui-radius-md)] border bg-[var(--ui-bg-surface)] flex flex-wrap items-center justify-between gap-1.5 text-sm transition-all shadow-inner cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ui-primary)]',
-                disabled
-                  ? 'opacity-50 cursor-not-allowed border-[var(--ui-border-subtle)]'
-                  : 'border-[var(--ui-border-default)] hover:border-[var(--ui-border-strong)]'
-              )}
-            >
-              <div className="flex flex-wrap items-center gap-1.5 flex-1">
-                {selectedValues.length === 0 ? (
-                  <span className="text-[var(--ui-text-muted)] text-sm">{placeholder}</span>
-                ) : (
-                  <>
-                    {selectedValues.slice(0, maxCount).map((val) => {
-                      const opt = options.find((o) => o.value === val);
-                      return (
-                        <Chip
-                          key={val}
-                          size="sm"
-                          variant="primary"
-                          onRemove={() => removeTag(val, {} as any)}
-                        >
-                          {opt?.label || val}
-                        </Chip>
-                      );
-                    })}
-                    {selectedValues.length > maxCount && (
-                      <Chip size="sm" variant="secondary">
-                        +{selectedValues.length - maxCount} more
-                      </Chip>
-                    )}
-                  </>
-                )}
-              </div>
-
-              <div className="flex items-center gap-1 text-[var(--ui-text-muted)]">
-                {selectedValues.length > 0 && !disabled && (
-                  <span
-                    onClick={clearAll}
-                    className="p-1 rounded-full hover:bg-[var(--ui-bg-tertiary)] hover:text-[var(--ui-text-primary)] transition-colors cursor-pointer"
-                  >
-                    <X className="w-3.5 h-3.5" />
-                  </span>
-                )}
-                <ChevronsUpDown className="w-4 h-4 opacity-50 shrink-0" />
-              </div>
-            </div>
-          }
-        >
-          <div className="p-2 w-76 rounded-2xl bg-[var(--ui-bg-surface)] backdrop-blur-2xl border border-[var(--ui-border-default)] shadow-2xl space-y-2">
-            <div className="relative flex items-center">
-              <Search className="absolute left-2.5 w-3.5 h-3.5 text-[var(--ui-text-muted)] pointer-events-none" />
-              <input
-                type="text"
-                autoFocus
-                placeholder={searchPlaceholder}
-                value={search}
-                onChange={(e) => {
-                  setSearch(e.target.value);
-                  setHighlightedIndex(0);
-                }}
-                onKeyDown={handleSearchKeyDown}
-                className="w-full h-8 pl-8 pr-3 text-xs rounded-xl bg-[var(--ui-bg-secondary)] border border-[var(--ui-border-subtle)] focus:outline-none focus:border-[var(--ui-primary)] text-[var(--ui-text-primary)]"
-              />
-            </div>
-
-            <div className="max-h-56 overflow-y-auto space-y-0.5" role="listbox">
-              {filteredOptions.length === 0 ? (
-                <div className="py-4 text-center text-xs text-[var(--ui-text-muted)]">No options found.</div>
-              ) : (
-                filteredOptions.map((opt, index) => {
-                  const isChecked = selectedValues.includes(opt.value);
-                  const isHighlighted = highlightedIndex === index;
-
-                  return (
-                    <div
-                      key={opt.value}
-                      role="option"
-                      aria-selected={isChecked}
-                      aria-disabled={opt.disabled}
-                      onClick={() => !opt.disabled && toggleOption(opt.value)}
-                      className={cn(
-                        'flex items-center justify-between px-3 py-2 rounded-xl text-xs font-medium transition-colors select-none',
-                        opt.disabled
-                          ? 'opacity-40 cursor-not-allowed text-[var(--ui-text-muted)]'
-                          : 'cursor-pointer',
-                        isChecked && 'text-[var(--ui-primary)] font-semibold',
-                        isHighlighted && !opt.disabled && 'bg-[var(--ui-primary)]/15'
-                      )}
-                    >
-                      <div className="flex items-center gap-2 truncate">
-                        {opt.icon}
-                        <span>{opt.label}</span>
-                      </div>
-                      {isChecked && <Check className="w-3.5 h-3.5 text-[var(--ui-primary)] shrink-0" />}
-                    </div>
-                  );
-                })
-              )}
-            </div>
-          </div>
-        </Popover>
-      </div>
-    );
-  }
-);
-MultiSelect.displayName = 'MultiSelect';
+import React, { forwardRef, useState, useRef, useEffect, useId } from 'react';
+import { Check, ChevronsUpDown, Search, X } from 'lucide-react';
+import { cn } from '../utils/cn';
+import { Popover } from '../overlays/Popover';
+import { Chip } from '../data-display/Chip';
+
+export interface ComboboxOption {
+  value: string;
+  label: string;
+  description?: string;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+}
+
+export interface ComboboxProps {
+  options: ComboboxOption[];
+  value?: string;
+  defaultValue?: string;
+  onChange?: (val: string) => void;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  emptyText?: string;
+  disabled?: boolean;
+  clearable?: boolean;
+  className?: string;
+  name?: string;
+  id?: string;
+  'aria-label'?: string;
+}
+
+export const Combobox = forwardRef<HTMLDivElement, ComboboxProps>(
+  (
+    {
+      options,
+      value: controlledVal,
+      defaultValue = '',
+      onChange,
+      placeholder = 'Select option...',
+      searchPlaceholder = 'Search items...',
+      emptyText = 'No items found.',
+      disabled = false,
+      clearable = true,
+      className,
+      name,
+      id: customId,
+      'aria-label': ariaLabel = 'Select option',
+    },
+    ref
+  ) => {
+    const baseId = useId();
+    const comboId = customId || `combobox-${baseId}`;
+    const listboxId = `listbox-${baseId}`;
+
+    const [internalVal, setInternalVal] = useState(defaultValue);
+    const isControlled = controlledVal !== undefined;
+    const selectedValue = isControlled ? controlledVal : internalVal;
+
+    const [search, setSearch] = useState('');
+    const [isOpen, setIsOpen] = useState(false);
+    const [highlightIndex, setHighlightIndex] = useState(0);
+
+    const searchInputRef = useRef<HTMLInputElement>(null);
+    const triggerRef = useRef<HTMLButtonElement>(null);
+
+    const filteredOptions = options.filter(
+      (opt) =>
+        opt.label.toLowerCase().includes(search.toLowerCase()) ||
+        opt.value.toLowerCase().includes(search.toLowerCase()) ||
+        (opt.description && opt.description.toLowerCase().includes(search.toLowerCase()))
+    );
+
+    const selectedOption = options.find((opt) => opt.value === selectedValue);
+
+    // Keep highlight index valid
+    useEffect(() => {
+      if (filteredOptions.length > 0) {
+        setHighlightIndex((prev) => Math.min(prev, filteredOptions.length - 1));
+      }
+    }, [filteredOptions.length]);
+
+    const handleSelect = (val: string) => {
+      if (!isControlled) {
+        setInternalVal(val);
+      }
+      onChange?.(val);
+      setIsOpen(false);
+      setSearch('');
+      triggerRef.current?.focus();
+    };
+
+    const handleClear = (e: React.MouseEvent) => {
+      e.stopPropagation();
+      if (!isControlled) {
+        setInternalVal('');
+      }
+      onChange?.('');
+    };
+
+    const handleKeyDown = (e: React.KeyboardEvent) => {
+      if (!isOpen) {
+        if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          setIsOpen(true);
+        }
+        return;
+      }
+
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        let next = highlightIndex + 1;
+        while (next < filteredOptions.length && filteredOptions[next]?.disabled) {
+          next++;
+        }
+        if (next < filteredOptions.length) {
+          setHighlightIndex(next);
+        }
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        let prev = highlightIndex - 1;
+        while (prev >= 0 && filteredOptions[prev]?.disabled) {
+          prev--;
+        }
+        if (prev >= 0) {
+          setHighlightIndex(prev);
+        }
+      } else if (e.key === 'Home') {
+        e.preventDefault();
+        let first = 0;
+        while (first < filteredOptions.length && filteredOptions[first]?.disabled) {
+          first++;
+        }
+        setHighlightIndex(first);
+      } else if (e.key === 'End') {
+        e.preventDefault();
+        let last = filteredOptions.length - 1;
+        while (last >= 0 && filteredOptions[last]?.disabled) {
+          last--;
+        }
+        setHighlightIndex(last);
+      } else if (e.key === 'Enter') {
+        e.preventDefault();
+        const highlighted = filteredOptions[highlightIndex];
+        if (highlighted && !highlighted.disabled) {
+          handleSelect(highlighted.value);
+        }
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        setIsOpen(false);
+        triggerRef.current?.focus();
+      }
+    };
+
+    const activeDescendantId =
+      filteredOptions[highlightIndex]
+        ? `combobox-opt-${baseId}-${filteredOptions[highlightIndex].value}`
+        : undefined;
+
+    return (
+      <div ref={ref} className={cn('relative w-full', className)}>
+        {name && <input type="hidden" name={name} value={selectedValue} />}
+        <Popover
+          isOpen={isOpen}
+          onClose={() => setIsOpen(false)}
+          trigger={
+            <button
+              ref={triggerRef}
+              id={comboId}
+              type="button"
+              disabled={disabled}
+              role="combobox"
+              aria-expanded={isOpen}
+              aria-haspopup="listbox"
+              aria-controls={isOpen ? listboxId : undefined}
+              aria-label={ariaLabel}
+              onClick={() => !disabled && setIsOpen(!isOpen)}
+              onKeyDown={handleKeyDown}
+              className={cn(
+                'w-full h-10 px-3.5 rounded-[var(--ui-radius-md)] border bg-[var(--ui-bg-surface)] text-left flex items-center justify-between text-sm transition-all shadow-inner cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ui-primary)]',
+                disabled
+                  ? 'opacity-50 cursor-not-allowed border-[var(--ui-border-subtle)]'
+                  : 'border-[var(--ui-border-default)] hover:border-[var(--ui-border-strong)]'
+              )}
+            >
+              <div className="flex items-center gap-2.5 truncate">
+                {selectedOption?.icon}
+                <span className={selectedOption ? 'text-[var(--ui-text-primary)] font-medium' : 'text-[var(--ui-text-muted)]'}>
+                  {selectedOption ? selectedOption.label : placeholder}
+                </span>
+              </div>
+
+              <div className="flex items-center gap-1 text-[var(--ui-text-muted)]">
+                {clearable && selectedValue && !disabled && (
+                  <span
+                    onClick={handleClear}
+                    className="p-1 rounded-full hover:bg-[var(--ui-bg-tertiary)] hover:text-[var(--ui-text-primary)] transition-colors cursor-pointer"
+                  >
+                    <X className="w-3.5 h-3.5" />
+                  </span>
+                )}
+                <ChevronsUpDown className="w-4 h-4 opacity-50 shrink-0" />
+              </div>
+            </button>
+          }
+        >
+          <div className="p-2 w-72 rounded-2xl bg-[var(--ui-bg-surface)] backdrop-blur-2xl border border-[var(--ui-border-default)] shadow-2xl space-y-2">
+            <div className="relative flex items-center">
+              <Search className="absolute left-2.5 w-3.5 h-3.5 text-[var(--ui-text-muted)] pointer-events-none" />
+              <input
+                ref={searchInputRef}
+                type="text"
+                autoFocus
+                placeholder={searchPlaceholder}
+                value={search}
+                onChange={(e) => {
+                  setSearch(e.target.value);
+                  setHighlightIndex(0);
+                }}
+                onKeyDown={handleKeyDown}
+                role="combobox"
+                aria-autocomplete="list"
+                aria-expanded="true"
+                aria-controls={listboxId}
+                aria-activedescendant={activeDescendantId}
+                className="w-full h-8 pl-8 pr-3 text-xs rounded-xl bg-[var(--ui-bg-secondary)] border border-[var(--ui-border-subtle)] focus:outline-none focus:border-[var(--ui-primary)] text-[var(--ui-text-primary)] placeholder:text-[var(--ui-text-muted)]"
+              />
+            </div>
+
+            <div id={listboxId} className="max-h-56 overflow-y-auto space-y-0.5" role="listbox">
+              {filteredOptions.length === 0 ? (
+                <div className="py-4 text-center text-xs text-[var(--ui-text-muted)]">{emptyText}</div>
+              ) : (
+                filteredOptions.map((opt, idx) => {
+                  const isSelected = opt.value === selectedValue;
+                  const isHighlighted = idx === highlightIndex;
+                  const optId = `combobox-opt-${baseId}-${opt.value}`;
+
+                  return (
+                    <div
+                      key={opt.value}
+                      id={optId}
+                      role="option"
+                      aria-selected={isSelected}
+                      aria-disabled={opt.disabled}
+                      onClick={() => !opt.disabled && handleSelect(opt.value)}
+                      onMouseEnter={() => !opt.disabled && setHighlightIndex(idx)}
+                      className={cn(
+                        'flex items-center justify-between px-3 py-2 rounded-xl text-xs font-medium cursor-pointer transition-colors select-none',
+                        opt.disabled && 'opacity-40 cursor-not-allowed pointer-events-none',
+                        isSelected
+                          ? 'bg-[var(--ui-primary)] text-white font-semibold shadow-xs'
+                          : isHighlighted
+                          ? 'bg-[var(--ui-bg-tertiary)] text-[var(--ui-text-primary)]'
+                          : 'text-[var(--ui-text-primary)]'
+                      )}
+                    >
+                      <div className="flex items-center gap-2 truncate">
+                        {opt.icon}
+                        <div>
+                          <span className="block truncate">{opt.label}</span>
+                          {opt.description && (
+                            <span className={cn('text-[10px] block truncate', isSelected ? 'text-white/80' : 'text-[var(--ui-text-muted)]')}>
+                              {opt.description}
+                            </span>
+                          )}
+                        </div>
+                      </div>
+
+                      {isSelected && <Check className="w-3.5 h-3.5 shrink-0" />}
+                    </div>
+                  );
+                })
+              )}
+            </div>
+          </div>
+        </Popover>
+      </div>
+    );
+  }
+);
+Combobox.displayName = 'Combobox';
+
+/* -------------------------------------------------------------------------------------------------
+ * MultiSelect Component
+ * -----------------------------------------------------------------------------------------------*/
+export interface MultiSelectProps {
+  options: ComboboxOption[];
+  value?: string[];
+  defaultValue?: string[];
+  onChange?: (val: string[]) => void;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  maxCount?: number;
+  disabled?: boolean;
+  className?: string;
+}
+
+export const MultiSelect = forwardRef<HTMLDivElement, MultiSelectProps>(
+  (
+    {
+      options,
+      value: controlledVal,
+      defaultValue = [],
+      onChange,
+      placeholder = 'Select items...',
+      searchPlaceholder = 'Search options...',
+      maxCount = 3,
+      disabled = false,
+      className,
+    },
+    ref
+  ) => {
+    const [internalVal, setInternalVal] = useState<string[]>(defaultValue);
+    const isControlled = controlledVal !== undefined;
+    const selectedValues = isControlled ? controlledVal : internalVal;
+
+    const [search, setSearch] = useState('');
+    const [isOpen, setIsOpen] = useState(false);
+    const [highlightedIndex, setHighlightedIndex] = useState(0);
+
+    const filteredOptions = options.filter(
+      (opt) =>
+        opt.label.toLowerCase().includes(search.toLowerCase()) ||
+        opt.value.toLowerCase().includes(search.toLowerCase())
+    );
+
+    const toggleOption = (val: string) => {
+      const opt = options.find((o) => o.value === val);
+      if (opt?.disabled) return;
+
+      const next = selectedValues.includes(val)
+        ? selectedValues.filter((v) => v !== val)
+        : [...selectedValues, val];
+      if (!isControlled) {
+        setInternalVal(next);
+      }
+      onChange?.(next);
+    };
+
+    const removeTag = (val: string, e?: React.MouseEvent) => {
+      e?.stopPropagation?.();
+      const next = selectedValues.filter((v) => v !== val);
+      if (!isControlled) {
+        setInternalVal(next);
+      }
+      onChange?.(next);
+    };
+
+    const clearAll = (e?: React.MouseEvent) => {
+      e?.stopPropagation?.();
+      if (!isControlled) {
+        setInternalVal([]);
+      }
+      onChange?.([]);
+    };
+
+    const handleSearchKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (filteredOptions.length === 0) return;
+
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        setHighlightedIndex((prev) => {
+          let next = (prev + 1) % filteredOptions.length;
+          while (filteredOptions[next]?.disabled && next !== prev) {
+            next = (next + 1) % filteredOptions.length;
+          }
+          return next;
+        });
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        setHighlightedIndex((prev) => {
+          let next = (prev - 1 + filteredOptions.length) % filteredOptions.length;
+          while (filteredOptions[next]?.disabled && next !== prev) {
+            next = (next - 1 + filteredOptions.length) % filteredOptions.length;
+          }
+          return next;
+        });
+      } else if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        const current = filteredOptions[highlightedIndex];
+        if (current && !current.disabled) {
+          toggleOption(current.value);
+        }
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        setIsOpen(false);
+      }
+    };
+
+    return (
+      <div ref={ref} className={cn('relative w-full', className)}>
+        <Popover
+          isOpen={isOpen}
+          onClose={() => setIsOpen(false)}
+          trigger={
+            <div
+              tabIndex={disabled ? -1 : 0}
+              role="combobox"
+              aria-expanded={isOpen}
+              aria-haspopup="listbox"
+              onClick={() => !disabled && setIsOpen(!isOpen)}
+              onKeyDown={(e) => {
+                if ((e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') && !disabled) {
+                  e.preventDefault();
+                  setIsOpen(true);
+                }
+              }}
+              className={cn(
+                'min-h-10 py-1.5 px-3 rounded-[var(--ui-radius-md)] border bg-[var(--ui-bg-surface)] flex flex-wrap items-center justify-between gap-1.5 text-sm transition-all shadow-inner cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ui-primary)]',
+                disabled
+                  ? 'opacity-50 cursor-not-allowed border-[var(--ui-border-subtle)]'
+                  : 'border-[var(--ui-border-default)] hover:border-[var(--ui-border-strong)]'
+              )}
+            >
+              <div className="flex flex-wrap items-center gap-1.5 flex-1">
+                {selectedValues.length === 0 ? (
+                  <span className="text-[var(--ui-text-muted)] text-sm">{placeholder}</span>
+                ) : (
+                  <>
+                    {selectedValues.slice(0, maxCount).map((val) => {
+                      const opt = options.find((o) => o.value === val);
+                      return (
+                        <Chip
+                          key={val}
+                          size="sm"
+                          variant="primary"
+                          onRemove={() => removeTag(val, {} as any)}
+                        >
+                          {opt?.label || val}
+                        </Chip>
+                      );
+                    })}
+                    {selectedValues.length > maxCount && (
+                      <Chip size="sm" variant="secondary">
+                        +{selectedValues.length - maxCount} more
+                      </Chip>
+                    )}
+                  </>
+                )}
+              </div>
+
+              <div className="flex items-center gap-1 text-[var(--ui-text-muted)]">
+                {selectedValues.length > 0 && !disabled && (
+                  <span
+                    onClick={clearAll}
+                    className="p-1 rounded-full hover:bg-[var(--ui-bg-tertiary)] hover:text-[var(--ui-text-primary)] transition-colors cursor-pointer"
+                  >
+                    <X className="w-3.5 h-3.5" />
+                  </span>
+                )}
+                <ChevronsUpDown className="w-4 h-4 opacity-50 shrink-0" />
+              </div>
+            </div>
+          }
+        >
+          <div className="p-2 w-76 rounded-2xl bg-[var(--ui-bg-surface)] backdrop-blur-2xl border border-[var(--ui-border-default)] shadow-2xl space-y-2">
+            <div className="relative flex items-center">
+              <Search className="absolute left-2.5 w-3.5 h-3.5 text-[var(--ui-text-muted)] pointer-events-none" />
+              <input
+                type="text"
+                autoFocus
+                placeholder={searchPlaceholder}
+                value={search}
+                onChange={(e) => {
+                  setSearch(e.target.value);
+                  setHighlightedIndex(0);
+                }}
+                onKeyDown={handleSearchKeyDown}
+                className="w-full h-8 pl-8 pr-3 text-xs rounded-xl bg-[var(--ui-bg-secondary)] border border-[var(--ui-border-subtle)] focus:outline-none focus:border-[var(--ui-primary)] text-[var(--ui-text-primary)]"
+              />
+            </div>
+
+            <div className="max-h-56 overflow-y-auto space-y-0.5" role="listbox">
+              {filteredOptions.length === 0 ? (
+                <div className="py-4 text-center text-xs text-[var(--ui-text-muted)]">No options found.</div>
+              ) : (
+                filteredOptions.map((opt, index) => {
+                  const isChecked = selectedValues.includes(opt.value);
+                  const isHighlighted = highlightedIndex === index;
+
+                  return (
+                    <div
+                      key={opt.value}
+                      role="option"
+                      aria-selected={isChecked}
+                      aria-disabled={opt.disabled}
+                      onClick={() => !opt.disabled && toggleOption(opt.value)}
+                      className={cn(
+                        'flex items-center justify-between px-3 py-2 rounded-xl text-xs font-medium transition-colors select-none',
+                        opt.disabled
+                          ? 'opacity-40 cursor-not-allowed text-[var(--ui-text-muted)]'
+                          : 'cursor-pointer',
+                        isChecked && 'text-[var(--ui-primary)] font-semibold',
+                        isHighlighted && !opt.disabled && 'bg-[var(--ui-primary)]/15'
+                      )}
+                    >
+                      <div className="flex items-center gap-2 truncate">
+                        {opt.icon}
+                        <span>{opt.label}</span>
+                      </div>
+                      {isChecked && <Check className="w-3.5 h-3.5 text-[var(--ui-primary)] shrink-0" />}
+                    </div>
+                  );
+                })
+              )}
+            </div>
+          </div>
+        </Popover>
+      </div>
+    );
+  }
+);
+MultiSelect.displayName = 'MultiSelect';