@exotic-holidays/ui 0.1.0

package/src/base-components/SearchableSelect.tsx

@@ -0,0 +1,734 @@
+'use client';
+
+import React, { useState, useEffect, useRef, useCallback } from 'react';
+import ReactDOM from 'react-dom';
+import { cn } from '../helpers/cn';
+import { ChevronDown, X, Search, Loader2 } from 'lucide-react';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface SearchableSelectOptionConfig<T = Record<string, unknown>> {
+    /** Key on the option object to use as the display label (default: 'name') */
+    label: string;
+    /** Key on the option object to use as the value (default: 'id') */
+    value: string;
+    /** Keys to search/filter on (default: [label]) */
+    keysToSearch?: string[];
+    /** Custom label render function */
+    labelFn?: (item: T) => string;
+    /** Custom option render function (for dropdown items) */
+    renderOption?: (item: T) => React.ReactNode;
+}
+
+export interface CreatableConfig<T = Record<string, unknown>> {
+    /** When to show the add-new button: true/'always' = always, 'with-content' = only when search has text */
+    visible: boolean | 'always' | 'with-content';
+    /** Position of the add-new button relative to the options list */
+    position: 'top' | 'bottom';
+    /** Action to execute when add-new is clicked. Return the new option object to auto-select it, or null/undefined to skip. */
+    action: (searchValue: string, setIsOpen: (v: boolean) => void) => Promise<T | null | undefined> | T | null | undefined;
+    /** Custom render for the add-new button area */
+    content?: (props: { searchValue: string; setDropdownOpen: (v: boolean) => void }) => React.ReactNode;
+}
+
+export interface SearchableSelectProps<T = Record<string, unknown>> {
+    /** Options array (for sync mode) */
+    options?: T[];
+    /** Callback fires on value change. Single: (value, selectedObj). Multi: (values[], selectedObjs[]) */
+    onChange: (value: string | number | (string | number)[], selected: T | T[]) => void;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Enable multi-select */
+    multiple?: boolean;
+    /** Default selected value(s). Single: an option object. Multi: an array of option objects. */
+    defaultValue?: T | T[];
+    /** Option config — keys for label/value, search keys, custom render */
+    option?: SearchableSelectOptionConfig<T>;
+    /** Creatable config — add-new button */
+    creatable?: CreatableConfig<T>;
+    /** Additional className on the outer wrapper */
+    className?: string;
+    /** Enable search filtering (default: true) */
+    isSearchable?: boolean;
+    /** Show clear button when a value is selected */
+    allowClear?: boolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Label text above the select */
+    label?: string;
+    /** Error message below the select */
+    error?: string;
+    /** Show required indicator on the label */
+    isRequired?: boolean;
+    /** Background surface level */
+    surface?: 0 | 1;
+}
+
+export interface AsyncSearchableSelectProps<T = Record<string, unknown>> extends Omit<SearchableSelectProps<T>, 'options'> {
+    /** Async loader — receives (searchString, pageNumber) and should return a promise resolving to an array of options */
+    loadOptions: (search: string, page: number) => Promise<T[]>;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+const DEFAULT_OPTION_CONFIG: SearchableSelectOptionConfig = {
+    label: 'name',
+    value: 'id',
+};
+
+// ─── Exported Select Wrappers ────────────────────────────────────────────────
+
+export const SearchableSelect = <T extends Record<string, unknown>>({
+    options = [],
+    ...props
+}: SearchableSelectProps<T>) => {
+    return <SelectCore<T> async={false} options={options} loadOptions={async () => []} {...props} />;
+};
+
+export const AsyncSearchableSelect = <T extends Record<string, unknown>>({
+    loadOptions,
+    ...props
+}: AsyncSearchableSelectProps<T>) => {
+    return <SelectCore<T> async options={[]} loadOptions={loadOptions} {...props} />;
+};
+
+// ─── Core Component ──────────────────────────────────────────────────────────
+
+interface SelectCoreProps<T> extends SearchableSelectProps<T> {
+    async: boolean;
+    loadOptions: (search: string, page: number) => Promise<T[]>;
+}
+
+function SelectCore<T extends Record<string, unknown>>({
+    async: isAsync,
+    options = [],
+    loadOptions,
+    onChange,
+    placeholder = 'Select...',
+    multiple = false,
+    defaultValue,
+    option: optionConfig,
+    creatable,
+    className,
+    isSearchable = true,
+    allowClear = false,
+    disabled = false,
+    label,
+    error,
+    isRequired,
+    surface = 0,
+}: SelectCoreProps<T>) {
+    const opt = { ...DEFAULT_OPTION_CONFIG, ...optionConfig } as SearchableSelectOptionConfig<T>;
+
+    // ── State ────────────────────────────────────────────────────────────────
+    const [isOpen, setIsOpen] = useState(false);
+    const [value, setValue] = useState<string | number | (string | number)[]>(() =>
+        multiple ? [] : ''
+    );
+    const [selectedValue, setSelectedValue] = useState<T | T[]>(() =>
+        multiple ? [] : ({} as T)
+    );
+    const [highlightedIndex, setHighlightedIndex] = useState<number | null>(null);
+    const [searchValue, setSearchValue] = useState('');
+
+    // Sync-mode data
+    const [selectData, setSelectData] = useState<T[]>([]);
+    const [masterData, setMasterData] = useState<T[]>([]);
+
+    // Async-mode data
+    const [asyncSelectData, setAsyncSelectData] = useState<T[]>([]);
+    const [page, setPage] = useState(1);
+    const [isSearching, setIsSearching] = useState(false);
+    const [isOptionLoading, setIsOptionLoading] = useState(false);
+    const [gotAllData, setGotAllData] = useState(false);
+
+    // Refs
+    const containerRef = useRef<HTMLDivElement>(null);
+    const controlRef = useRef<HTMLDivElement>(null);
+    const searchInputRef = useRef<HTMLInputElement>(null);
+    const searchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const highlightedRef = useRef<HTMLLIElement>(null);
+    const dropdownRef = useRef<HTMLDivElement>(null);
+
+    // Dropdown position (for portal rendering)
+    const [dropdownPos, setDropdownPos] = useState<{ top: number; left: number; width: number; flipToTop: boolean }>({ top: 0, left: 0, width: 0, flipToTop: false });
+
+    // ── Computed helpers ─────────────────────────────────────────────────────
+    const displayData: T[] = isAsync ? asyncSelectData : selectData;
+
+    const getLabel = useCallback(
+        (item: T): string => {
+            if (opt.labelFn) return opt.labelFn(item);
+            return String(item[opt.label] ?? '');
+        },
+        [opt]
+    );
+
+    const hasValue = multiple
+        ? Array.isArray(value) && (value as (string | number)[]).length > 0
+        : value !== '' && value !== 0;
+
+    // ── Calculate dropdown position (auto-flip when clipped at bottom) ───────
+    const DROPDOWN_ESTIMATED_HEIGHT = 300; // search bar + max-height options + padding
+    const GAP = 6;
+
+    const updateDropdownPosition = useCallback(() => {
+        if (!controlRef.current) return;
+        const rect = controlRef.current.getBoundingClientRect();
+        const spaceBelow = window.innerHeight - rect.bottom;
+        const spaceAbove = rect.top;
+        const openBelow = spaceBelow >= DROPDOWN_ESTIMATED_HEIGHT || spaceBelow >= spaceAbove;
+
+        setDropdownPos({
+            top: openBelow ? rect.bottom + GAP : rect.top - GAP,
+            left: rect.left,
+            width: rect.width,
+            flipToTop: !openBelow,
+        });
+    }, []);
+
+    // ── Scroll highlighted into view ─────────────────────────────────────────
+    useEffect(() => {
+        highlightedRef.current?.scrollIntoView({ block: 'nearest' });
+    }, [highlightedIndex]);
+
+    // ── Sync options → master data ───────────────────────────────────────────
+    useEffect(() => {
+        if (options.length > 0) {
+            setMasterData(options);
+            setSelectData(options);
+        }
+    }, [options]);
+
+    // ── Default value ────────────────────────────────────────────────────────
+    const defaultValString = JSON.stringify(defaultValue || '');
+    useEffect(() => {
+        if (!defaultValue) return;
+        if (multiple && Array.isArray(defaultValue) && defaultValue.length > 0) {
+            const vals = (defaultValue as T[]).map((v) => v[opt.value] as string | number);
+            setSelectedValue(defaultValue as T[]);
+            setValue(vals);
+        } else if (!multiple && !Array.isArray(defaultValue) && (defaultValue as T)[opt.value] !== undefined) {
+            setSelectedValue(defaultValue as T);
+            setValue((defaultValue as T)[opt.value] as string | number);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [multiple, opt.value, defaultValString]);
+
+    // ── On open → setup ──────────────────────────────────────────────────────
+    useEffect(() => {
+        if (!isOpen) return;
+
+        updateDropdownPosition();
+
+        // Defer focus so the portal dropdown is mounted first
+        requestAnimationFrame(() => {
+            searchInputRef.current?.focus();
+        });
+        setHighlightedIndex(null);
+        setSearchValue('');
+
+        if (isAsync) {
+            setPage(1);
+            setGotAllData(false);
+            setIsOptionLoading(true);
+            loadOptions('', 1).then((initial) => {
+                setIsOptionLoading(false);
+                setAsyncSelectData(initial);
+                if (initial.length > 0) setHighlightedIndex(0);
+            });
+        } else {
+            setSelectData(masterData);
+            if (masterData.length > 0) setHighlightedIndex(0);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [isOpen]);
+
+    // ── Reposition on scroll / resize while open ─────────────────────────────
+    useEffect(() => {
+        if (!isOpen) return;
+        const handleReposition = () => updateDropdownPosition();
+        window.addEventListener('scroll', handleReposition, true);
+        window.addEventListener('resize', handleReposition);
+        return () => {
+            window.removeEventListener('scroll', handleReposition, true);
+            window.removeEventListener('resize', handleReposition);
+        };
+    }, [isOpen, updateDropdownPosition]);
+
+    // ── Click outside → close ────────────────────────────────────────────────
+    useEffect(() => {
+        const handler = (e: MouseEvent) => {
+            const target = e.target as Node;
+            if (
+                containerRef.current && !containerRef.current.contains(target) &&
+                dropdownRef.current && !dropdownRef.current.contains(target)
+            ) {
+                setIsOpen(false);
+                setHighlightedIndex(null);
+            }
+        };
+        window.addEventListener('click', handler);
+        return () => window.removeEventListener('click', handler);
+    }, []);
+
+    // ── Search handler ───────────────────────────────────────────────────────
+    const handleSearchChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+        const val = e.target.value;
+        setSearchValue(val);
+
+        if (isAsync) {
+            if (searchTimeoutRef.current) clearTimeout(searchTimeoutRef.current);
+            searchTimeoutRef.current = setTimeout(() => {
+                setIsSearching(true);
+                setPage(1);
+                setGotAllData(false);
+                loadOptions(val, 1).then((results) => {
+                    setAsyncSelectData(results);
+                    setHighlightedIndex(results.length > 0 ? 0 : null);
+                    setIsSearching(false);
+                });
+            }, 300);
+        } else {
+            filterSyncData(val);
+        }
+    };
+
+    const filterSyncData = (search: string) => {
+        const s = search.toLowerCase();
+        if (s === '') {
+            setSelectData(masterData);
+            setHighlightedIndex(masterData.length > 0 ? 0 : null);
+            return;
+        }
+        const keys = opt.keysToSearch ?? [opt.label];
+        const filtered = options.filter((item) =>
+            keys.some((key) => {
+                try {
+                    const v = item[key];
+                    const str = typeof v === 'string' ? v : String(v);
+                    return str.toLowerCase().includes(s);
+                } catch {
+                    return false;
+                }
+            })
+        );
+        setSelectData(filtered);
+        setHighlightedIndex(filtered.length > 0 ? 0 : null);
+    };
+
+    // ── Option click ─────────────────────────────────────────────────────────
+    const handleOptionClick = (e: React.MouseEvent, item: T) => {
+        e.stopPropagation();
+        const itemValue = item[opt.value] as string | number;
+
+        if (multiple) {
+            const curValues = value as (string | number)[];
+            const curSelected = selectedValue as T[];
+            if (curValues.includes(itemValue)) {
+                const newVals = curValues.filter((v) => v !== itemValue);
+                const newSel = curSelected.filter((s) => s[opt.value] !== itemValue);
+                setValue(newVals);
+                setSelectedValue(newSel);
+                onChange(newVals, newSel);
+            } else {
+                const newVals = [...curValues, itemValue];
+                const newSel = [...curSelected, item];
+                setValue(newVals);
+                setSelectedValue(newSel);
+                onChange(newVals, newSel);
+            }
+        } else {
+            setValue(itemValue);
+            setSelectedValue(item);
+            onChange(itemValue, item);
+            setIsOpen(false);
+        }
+    };
+
+    // ── Remove a multi tag ───────────────────────────────────────────────────
+    const removeTag = (e: React.MouseEvent, id: string | number) => {
+        e.stopPropagation();
+        const newVals = (value as (string | number)[]).filter((v) => v !== id);
+        const newSel = (selectedValue as T[]).filter((s) => s[opt.value] !== id);
+        setValue(newVals);
+        setSelectedValue(newSel);
+        onChange(newVals, newSel);
+    };
+
+    // ── Clear all ────────────────────────────────────────────────────────────
+    const handleClear = (e: React.MouseEvent) => {
+        e.stopPropagation();
+        if (multiple) {
+            setValue([]);
+            setSelectedValue([]);
+            onChange([], []);
+        } else {
+            setValue('');
+            setSelectedValue({} as T);
+            onChange('', {} as T);
+        }
+    };
+
+    // ── Keyboard (dropdown) ──────────────────────────────────────────────────
+    const handleDropdownKeyDown = (e: React.KeyboardEvent) => {
+        const data = displayData;
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                if (highlightedIndex === null) setHighlightedIndex(0);
+                else if (highlightedIndex < data.length - 1) setHighlightedIndex(highlightedIndex + 1);
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                if (highlightedIndex !== null && highlightedIndex > 0) setHighlightedIndex(highlightedIndex - 1);
+                break;
+            case 'Escape':
+                setIsOpen(false);
+                break;
+            case 'Enter':
+                e.preventDefault();
+                if (highlightedIndex !== null && data[highlightedIndex]) {
+                    handleOptionClick(e as unknown as React.MouseEvent, data[highlightedIndex]);
+                }
+                break;
+        }
+    };
+
+    // ── Keyboard (container – open select) ───────────────────────────────────
+    const handleContainerKeyDown = (e: React.KeyboardEvent) => {
+        if (disabled) return;
+        if (['Enter', ' ', 'ArrowDown'].includes(e.key)) {
+            e.preventDefault();
+            if (!isOpen) setIsOpen(true);
+        }
+    };
+
+    // ── Async scroll pagination ──────────────────────────────────────────────
+    const handleScroll = (e: React.UIEvent<HTMLUListElement>) => {
+        if (!isAsync || gotAllData || isSearching || isOptionLoading) return;
+        const t = e.currentTarget;
+        if (t.clientHeight + t.scrollTop >= t.scrollHeight - 1) {
+            setIsOptionLoading(true);
+            const nextPage = page + 1;
+            setPage(nextPage);
+            loadOptions(searchValue, nextPage).then((newItems) => {
+                if (newItems.length === 0) setGotAllData(true);
+                setAsyncSelectData((prev) => [...prev, ...newItems]);
+                setIsOptionLoading(false);
+            });
+        }
+    };
+
+    // ── Creatable action ─────────────────────────────────────────────────────
+    const handleAddNew = async (e: React.MouseEvent) => {
+        e.stopPropagation();
+        if (!creatable) return;
+        const newData = await creatable.action(searchValue, setIsOpen);
+        if (!newData) return;
+        const newVal = newData[opt.value] as string | number;
+
+        if (multiple) {
+            const curVals = value as (string | number)[];
+            if (!curVals.includes(newVal)) {
+                const newVals = [...curVals, newVal];
+                const newSel = [...(selectedValue as T[]), newData];
+                setValue(newVals);
+                setSelectedValue(newSel);
+                onChange(newVals, newSel);
+            }
+        } else {
+            if (value !== newVal) {
+                setValue(newVal);
+                setSelectedValue(newData);
+                onChange(newVal, newData);
+            }
+        }
+        setIsOpen(false);
+    };
+
+    // ── Creatable visibility helper ──────────────────────────────────────────
+    const isCreatableVisible = (() => {
+        if (!creatable) return false;
+        const vis = creatable.visible;
+        if (vis === true || vis === 'always') return true;
+        if (vis === 'with-content' && searchValue !== '') return true;
+        return false;
+    })();
+
+    // ── Check if an option value is selected ─────────────────────────────────
+    const isSelected = (item: T): boolean => {
+        const itemVal = item[opt.value] as string | number;
+        if (multiple) return (value as (string | number)[]).includes(itemVal);
+        return value === itemVal;
+    };
+
+    // ── Dropdown content (rendered via portal) ───────────────────────────────
+    const dropdownContent = isOpen ? (
+        <div
+            ref={dropdownRef}
+            className="fixed z-[9999] bg-surface-1 border border-border-subtle rounded-[10px] shadow-lg overflow-hidden"
+            style={{
+                ...(dropdownPos.flipToTop
+                    ? { bottom: window.innerHeight - dropdownPos.top, left: dropdownPos.left, width: dropdownPos.width }
+                    : { top: dropdownPos.top, left: dropdownPos.left, width: dropdownPos.width }),
+            }}
+            onKeyDown={handleDropdownKeyDown}
+        >
+            {/* Search input */}
+            {isSearchable && (
+                <div className="flex items-center gap-2 px-3 py-2.5 border-b border-border-subtle">
+                    <Search size={15} className="text-foreground-disabled shrink-0" />
+                    <input
+                        ref={searchInputRef}
+                        type="text"
+                        className="w-full bg-white text-[13px] text-foreground-1 outline-none placeholder:text-foreground-disabled"
+                        placeholder="Search..."
+                        value={searchValue}
+                        onChange={handleSearchChange}
+                        onClick={(e) => e.stopPropagation()}
+                        autoComplete="off"
+                        spellCheck={false}
+                        aria-label="Search options"
+                    />
+                    {isAsync && isSearching && (
+                        <Loader2 size={15} className="text-primary animate-spin shrink-0" />
+                    )}
+                </div>
+            )}
+
+            {/* Hidden focusable ref for non-searchable mode */}
+            {!isSearchable && <span ref={searchInputRef} tabIndex={-1} />}
+
+            {/* Add-new button (top) */}
+            {isCreatableVisible && creatable?.position === 'top' && (
+                <AddNewButton
+                    creatable={creatable}
+                    searchValue={searchValue}
+                    onAdd={handleAddNew}
+                    setIsOpen={setIsOpen}
+                />
+            )}
+
+            {/* Options list */}
+            <ul
+                className="max-h-[220px] overflow-y-auto py-1 custom-scrollbar"
+                role="listbox"
+                onScroll={handleScroll}
+            >
+                {displayData.length === 0 && !isOptionLoading && (
+                    <li className="px-3.5 py-3 text-center text-[12.5px] text-foreground-disabled">
+                        No options found
+                    </li>
+                )}
+
+                {displayData.map((item, idx) => (
+                    <li
+                        key={idx}
+                        ref={idx === highlightedIndex ? highlightedRef : null}
+                        role="option"
+                        aria-selected={isSelected(item)}
+                        className={cn(
+                            'flex items-center gap-2 px-3.5 py-2 text-[13px] cursor-pointer transition-colors',
+                            isSelected(item)
+                                ? 'bg-primary/10 text-primary font-medium'
+                                : 'text-foreground-1',
+                            idx === highlightedIndex && 'bg-surface-hover',
+                            isSelected(item) && idx === highlightedIndex && 'bg-primary/15'
+                        )}
+                        onClick={(e) => handleOptionClick(e, item)}
+                        onMouseEnter={() => setHighlightedIndex(idx)}
+                    >
+                        {/* Checkbox indicator for multi */}
+                        {multiple && (
+                            <span
+                                className={cn(
+                                    'w-4 h-4 rounded border-[1.5px] flex items-center justify-center shrink-0 transition-colors',
+                                    isSelected(item)
+                                        ? 'bg-primary border-primary'
+                                        : 'border-border-subtle bg-surface-0'
+                                )}
+                            >
+                                {isSelected(item) && (
+                                    <svg width="10" height="8" viewBox="0 0 10 8" fill="none">
+                                        <path d="M1 4L3.5 6.5L9 1" stroke="white" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+                                    </svg>
+                                )}
+                            </span>
+                        )}
+
+                        {/* Option label */}
+                        <span className="truncate">
+                            {opt.renderOption
+                                ? opt.renderOption(item)
+                                : getLabel(item)}
+                        </span>
+                    </li>
+                ))}
+
+                {/* Async pagination loader */}
+                {isAsync && isOptionLoading && (
+                    <li className="flex items-center justify-center py-3">
+                        <Loader2 size={18} className="text-primary animate-spin" />
+                    </li>
+                )}
+            </ul>
+
+            {/* Add-new button (bottom) */}
+            {isCreatableVisible && creatable?.position === 'bottom' && (
+                <AddNewButton
+                    creatable={creatable}
+                    searchValue={searchValue}
+                    onAdd={handleAddNew}
+                    setIsOpen={setIsOpen}
+                />
+            )}
+        </div>
+    ) : null;
+
+    // ── Render ───────────────────────────────────────────────────────────────
+    return (
+        <div className={cn('flex flex-col gap-1.5 w-full', className)}>
+            {/* Label */}
+            {label && (
+                <label className="text-[12px] font-normal text-foreground-subtle tracking-[0.3px] capitalize">
+                    {label}
+                    {isRequired && <span className="text-danger-alt ml-0.5">*</span>}
+                </label>
+            )}
+
+            {/* Select container */}
+            <div
+                ref={containerRef}
+                tabIndex={disabled ? -1 : 0}
+                onClick={() => {
+                    if (!disabled) setIsOpen((prev) => !prev);
+                }}
+                onKeyDown={handleContainerKeyDown}
+                className={cn(
+                    'relative',
+                    disabled && 'opacity-50 pointer-events-none'
+                )}
+            >
+                {/* Control */}
+                <div
+                    ref={controlRef}
+                    className={cn(
+                        'w-full border-[1.5px] rounded-[10px] px-3.5 py-2.5 flex items-center gap-2 cursor-pointer transition-all min-h-[42px]',
+                        isOpen
+                            ? `border-primary bg-surface-1`
+                            : `border-border-subtle bg-surface-1`,
+                        error && 'border-danger-alt focus:border-danger-alt'
+                    )}
+                >
+                    {/* Value area */}
+                    <div className="flex-1 flex items-center gap-1.5 flex-wrap min-w-0">
+                        {multiple ? (
+                            <>
+                                {(selectedValue as T[]).length === 0 ? (
+                                    <span className="text-[13.5px] text-foreground-subtle select-none">{placeholder}</span>
+                                ) : (
+                                    (selectedValue as T[]).map((item, i) => (
+                                        <span
+                                            key={i}
+                                            className="inline-flex items-center gap-1 bg-primary/10 text-primary text-[12px] font-semibold px-2.5 py-0.5 rounded-full"
+                                        >
+                                            <span className="truncate max-w-[120px]">{getLabel(item)}</span>
+                                            {!disabled && (
+                                                <button
+                                                    type="button"
+                                                    className="flex items-center justify-center hover:text-danger transition-colors cursor-pointer"
+                                                    onClick={(e) => removeTag(e, item[opt.value] as string | number)}
+                                                    aria-label={`Remove ${getLabel(item)}`}
+                                                >
+                                                    <X size={12} />
+                                                </button>
+                                            )}
+                                        </span>
+                                    ))
+                                )}
+                            </>
+                        ) : (
+                            <>
+                                {!hasValue ? (
+                                    <span className="text-[13.5px] text-foreground-subtle select-none">{placeholder}</span>
+                                ) : (
+                                    <span className="text-[13.5px] text-foreground-1 truncate">
+                                        {getLabel(selectedValue as T)}
+                                    </span>
+                                )}
+                            </>
+                        )}
+                    </div>
+
+                    {/* Indicators */}
+                    <div className="flex items-center gap-1 shrink-0">
+                        {allowClear && hasValue && !disabled && (
+                            <>
+                                <button
+                                    type="button"
+                                    className="flex items-center justify-center p-0.5 text-foreground-disabled hover:text-foreground-muted transition-colors cursor-pointer"
+                                    onClick={handleClear}
+                                    aria-label="Clear selection"
+                                >
+                                    <X size={15} />
+                                </button>
+                                <span className="w-px h-4 bg-border-subtle" />
+                            </>
+                        )}
+                        <div
+                            className={cn(
+                                'flex items-center justify-center text-foreground-disabled transition-transform duration-200',
+                                isOpen && 'rotate-180'
+                            )}
+                        >
+                            <ChevronDown size={16} />
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            {/* Error message */}
+            {error && <span className="text-[11px] text-danger-alt font-medium">{error}</span>}
+
+            {/* Dropdown rendered via portal to escape overflow containers */}
+            {typeof document !== 'undefined' &&
+                ReactDOM.createPortal(dropdownContent, document.body)}
+        </div>
+    );
+}
+
+// ─── Add New Button Sub-Component ────────────────────────────────────────────
+
+interface AddNewButtonProps<T> {
+    creatable: CreatableConfig<T>;
+    searchValue: string;
+    onAdd: (e: React.MouseEvent) => void;
+    setIsOpen: (v: boolean) => void;
+}
+
+function AddNewButton<T>({ creatable, searchValue, onAdd, setIsOpen }: AddNewButtonProps<T>) {
+    // Custom content renderer
+    if (creatable.content) {
+        return (
+            <div className="border-y border-border-subtle" onClick={onAdd}>
+                {creatable.content({ searchValue, setDropdownOpen: setIsOpen })}
+            </div>
+        );
+    }
+
+    return (
+        <div
+            className="flex items-center gap-2 px-3.5 py-2.5 border-y border-border-subtle text-primary hover:bg-surface-hover transition-colors cursor-pointer"
+            onClick={onAdd}
+        >
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" width="16" height="16" className="shrink-0">
+                <path d="M12 5V19M5 12H19" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+            </svg>
+            <span className="text-[13px] font-medium">
+                Add {searchValue === '' ? 'new' : ''}
+                {searchValue !== '' && <span className="font-semibold ml-1">{searchValue}</span>}
+            </span>
+        </div>
+    );
+}