frontend/src/components/Combobox/Combobox.tsx

@@ -1,15 +1,21 @@
-import { useState, useRef, useEffect } from 'react';
-import TextInput from '../TextInput/TextInput';
-import SearchResultList, { type SearchResultOption } from '../SearchResultList/SearchResultList';
+import { useState, useRef, useEffect } from "react";
+import clsx from "clsx";
+import TextInput from "../TextInput/TextInput";
+import { SearchIcon } from "../Icon/Icon";
+import SearchResultList, {
+  type SearchResultOption,
+} from "../SearchResultList/SearchResultList";
+import { useClickOutside } from "../../hooks/useClickOutside";
 
 export type ComboboxOption = SearchResultOption;
 
-export type ComboboxSize = 'sm' | 'md' | 'lg';
+export type ComboboxSize = "sm" | "md" | "lg";
 
 export interface ComboboxProps {
   options: ComboboxOption[];
   placeholder?: string;
-    label?: string;
+  label: string;
+  hideLabel?: boolean;
   size?: ComboboxSize;
   fullWidth?: boolean;
   customWidth?: string;
@@ -23,63 +29,56 @@ export interface ComboboxProps {
 }
 
 const widthClasses: Record<ComboboxSize, string> = {
-    sm: 'w-(--text-input-default-width-md)',
-    md: 'w-(--text-input-default-width-md)',
-    lg: 'w-(--text-input-default-width-lg)',
+  sm: "w-(--text-input-default-width-md)",
+  md: "w-(--text-input-default-width-md)",
+  lg: "w-(--text-input-default-width-lg)",
 };
 
-const dropdownWrapperClasses = 'absolute top-full left-0 z-50 w-full mt-(--spacing-sm)';
+const dropdownWrapperClasses =
+  "absolute top-full left-0 z-50 w-full mt-(--spacing-sm)";
 
-function SearchIcon({ className }: { className?: string }) {
-    return (
-        <svg
-            className={className}
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-        >
-            <circle cx="11" cy="11" r="8" />
-            <path d="M21 21l-4.35-4.35" />
-        </svg>
-    );
-}
-
-function useClickOutside(ref: React.RefObject<HTMLElement | null>, onClickOutside: () => void) {
-    useEffect(() => {
-        const handleClick = (event: MouseEvent) => {
-            if (ref.current && !ref.current.contains(event.target as Node)) {
-                onClickOutside();
-            }
-        };
-
-        document.addEventListener('mousedown', handleClick);
-        return () => document.removeEventListener('mousedown', handleClick);
-    }, [ref, onClickOutside]);
-}
-
-function useScrollIntoView(index: number, refs: React.RefObject<(HTMLDivElement | null)[]>) {
+/**
+ * Scrolls the focused item into view when navigating with arrow keys.
+ * Uses "nearest" to minimize scrolling - only scrolls if the item is outside the visible area.
+ */
+function useScrollIntoView(
+  index: number,
+  refs: React.RefObject<(HTMLDivElement | null)[]>,
+) {
   useEffect(() => {
     if (index >= 0 && refs.current[index]) {
-            refs.current[index]?.scrollIntoView({ block: 'nearest' });
+      refs.current[index]?.scrollIntoView({ block: "nearest" });
     }
   }, [index, refs]);
 }
 
-function filterOptions(options: ComboboxOption[], searchTerm: string): ComboboxOption[] {
+function filterOptions(
+  options: ComboboxOption[],
+  searchTerm: string,
+): ComboboxOption[] {
   const term = searchTerm.toLowerCase();
   return options.filter(
-        (opt) => opt.label.toLowerCase().includes(term) || opt.subtitle?.toLowerCase().includes(term),
+    (opt) =>
+      opt.label.toLowerCase().includes(term) ||
+      opt.subtitle?.toLowerCase().includes(term),
   );
 }
 
-function getNextIndex(currentIndex: number, direction: 'up' | 'down', maxIndex: number): number {
-    const next = currentIndex + (direction === 'down' ? 1 : -1);
+function getNextIndex(
+  currentIndex: number,
+  direction: "up" | "down",
+  maxIndex: number,
+): number {
+  const next = currentIndex + (direction === "down" ? 1 : -1);
   return Math.max(0, Math.min(next, maxIndex));
 }
 
+/**
+ * Determines what text to display in the input field.
+ * - If user is typing, show the search term
+ * - If multi-select mode, show nothing (selections appear as ListCards below)
+ * - If single-select with a selection, show the selected option's label
+ */
 function getDisplayValue(
   options: ComboboxOption[],
   selectedValues: string[],
@@ -89,46 +88,53 @@ function getDisplayValue(
   if (searchTerm) return searchTerm;
 
   if (multiple) {
-        return '';
+    return "";
   }
 
-    if (selectedValues.length === 0) return '';
+  if (selectedValues.length === 0) return "";
 
-    return options.find((opt) => opt.value === selectedValues[0])?.label || '';
+  return options.find((opt) => opt.value === selectedValues[0])?.label || "";
 }
 
 export default function Combobox({
   options,
-    placeholder = 'Search...',
+  placeholder = "Search...",
   label,
-    size = 'md',
+  hideLabel = false,
+  size = "md",
   fullWidth = false,
   customWidth,
   dropdownHeight = 300,
-    noResultsText = 'No results found',
+  noResultsText = "No results found",
   multiple = false,
   value,
   onChange,
   onSearchChange,
 }: ComboboxProps) {
-    // Normalize value to array for internal use
-    const selectedValues: string[] = value === undefined ? [] : Array.isArray(value) ? value : [value];
+  // Convert value (undefined | string | string[]) to always be an array
+  const selectedValues: string[] =
+    value === undefined ? [] : Array.isArray(value) ? value : [value];
 
-    // State
   const [isOpen, setIsOpen] = useState(false);
-    const [searchTerm, setSearchTerm] = useState('');
+  const [searchTerm, setSearchTerm] = useState("");
   const [focusedIndex, setFocusedIndex] = useState(-1);
 
   const containerRef = useRef<HTMLDivElement>(null);
   const itemRefs = useRef<(HTMLDivElement | null)[]>([]);
 
   // Derived state - skip local filtering when onSearchChange is provided (API handles filtering)
-    const filteredOptions = onSearchChange ? options : filterOptions(options, searchTerm);
-    const displayValue = getDisplayValue(options, selectedValues, multiple, searchTerm);
+  const filteredOptions = onSearchChange
+    ? options
+    : filterOptions(options, searchTerm);
+  const displayValue = getDisplayValue(
+    options,
+    selectedValues,
+    multiple,
+    searchTerm,
+  );
 
   const closeDropdown = () => setIsOpen(false);
 
-    // Hooks
   useClickOutside(containerRef, closeDropdown);
   useScrollIntoView(focusedIndex, itemRefs);
 
@@ -138,10 +144,10 @@ export default function Combobox({
     setSearchTerm(value);
     onSearchChange?.(value);
 
-        if (value === '') {
+    if (value === "") {
       // Clear selection when user empties the field in single-select mode
       if (!multiple && selectedValues.length > 0) {
-                onChange?.('');
+        onChange?.("");
       }
       closeDropdown();
     } else {
@@ -161,14 +167,14 @@ export default function Combobox({
       // Replace selection in single-select mode
       onChange?.(option.value);
     }
-        setSearchTerm(''); // Clear search so selected label shows
+    setSearchTerm(""); // Clear search so selected label shows
     closeDropdown();
   };
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
     // Open dropdown on arrow keys when closed (only if we have options to show)
     if (!isOpen) {
-            if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      if (e.key === "ArrowDown" || e.key === "ArrowUp") {
         if (filteredOptions.length > 0) {
           setIsOpen(true);
         }
@@ -179,35 +185,39 @@ export default function Combobox({
 
     // Handle navigation when open
     switch (e.key) {
-            case 'ArrowDown':
+      case "ArrowDown":
         e.preventDefault();
-                setFocusedIndex((prev) => getNextIndex(prev, 'down', filteredOptions.length - 1));
+        setFocusedIndex((prev) =>
+          getNextIndex(prev, "down", filteredOptions.length - 1),
+        );
         break;
 
-            case 'ArrowUp':
+      case "ArrowUp":
         e.preventDefault();
-                setFocusedIndex((prev) => getNextIndex(prev, 'up', filteredOptions.length - 1));
+        setFocusedIndex((prev) =>
+          getNextIndex(prev, "up", filteredOptions.length - 1),
+        );
         break;
 
-            case 'Enter':
+      case "Enter":
         e.preventDefault();
         if (focusedIndex >= 0 && focusedIndex < filteredOptions.length) {
           handleSelect(filteredOptions[focusedIndex]);
         }
         break;
 
-            case 'Escape':
-            case 'Tab':
+      case "Escape":
+      case "Tab":
         closeDropdown();
         break;
     }
   };
 
-    const containerClasses = fullWidth
-        ? 'relative w-full'
-        : customWidth
-          ? 'relative'
-          : `relative ${widthClasses[size]}`;
+  const containerClasses = clsx(
+    "relative",
+    fullWidth && "w-full",
+    !fullWidth && !customWidth && widthClasses[size],
+  );
   const widthStyle = customWidth ? { width: customWidth } : undefined;
 
   return (
@@ -219,10 +229,11 @@ export default function Combobox({
         onKeyDown={handleKeyDown}
         placeholder={placeholder}
         label={label}
+        hideLabel={hideLabel}
         size={size}
         fullWidth={fullWidth || !!customWidth}
         customWidth={customWidth}
-                icon={<SearchIcon />}
+        Icon={SearchIcon}
       />
 
       {isOpen && (

frontend/src/hooks/useClickOutside.ts

@@ -0,0 +1,17 @@
+import { useEffect } from "react";
+
+export function useClickOutside(
+  ref: React.RefObject<HTMLElement | null>,
+  onClickOutside: () => void,
+) {
+  useEffect(() => {
+    const handleClick = (event: MouseEvent) => {
+      if (ref.current && !ref.current.contains(event.target as Node)) {
+        onClickOutside();
+      }
+    };
+
+    document.addEventListener("mousedown", handleClick);
+    return () => document.removeEventListener("mousedown", handleClick);
+  }, [ref, onClickOutside]);
+}