indas-ui 0.0.1 → 0.1.0

package/dist/components/forms/dropdown/SingleSelect.js

@@ -0,0 +1,218 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from 'react';
+import * as SelectPrimitive from '@radix-ui/react-select';
+import * as Popover from '@radix-ui/react-popover';
+import { Check, ChevronDown, Search, X } from 'lucide-react';
+import { cn } from '../../../lib/utils.js';
+import { getDropdownClassName, dropdownSharedStyles, DropdownSearch, ClearButton, OptionImage } from './Dropdown.js';
+export function SingleSelect({ value, onValueChange, open, onOpenChange, disabled, placeholder, error, clearable, autoWidth, triggerClassName, className, id, 'aria-label': ariaLabel, searchable, searchTerm, setSearchTerm, filteredOptions, allOptions, loading, emptyMessage, showCreateOption, effectiveCreateOption, isCreating, allowCustomInput, createOptionLabel, handleCreateOption, handleClear, customFooter, variant = 'default', size = 'md', trailingAction, customTrigger, contentClassName }) {
+    // Find selected option from ALL options (not just filtered) to show label in trigger
+    // This ensures the selected value displays correctly even when options are still loading
+    const selectedOption = React.useMemo(() => {
+        return allOptions.find(opt => opt.value?.toString() === value?.toString());
+    }, [allOptions, value]);
+    // For combobox mode with allowCustomInput, use direct input value
+    const displayValue = React.useMemo(() => {
+        if (allowCustomInput && value && !selectedOption) {
+            // If there's a value but no matching option, it's a custom value
+            return value.toString();
+        }
+        return selectedOption?.label || '';
+    }, [allowCustomInput, value, selectedOption]);
+    // Track highlighted option index for keyboard navigation
+    const [highlightedIndex, setHighlightedIndex] = React.useState(0);
+    // The options actually RENDERED in the list (null/empty values stripped). Keyboard
+    // nav must index THIS array — the rendered rows and highlight use it too.
+    const displayOptions = React.useMemo(() => filteredOptions.filter(o => o.value != null && o.value !== ''), [filteredOptions]);
+    // Reset highlighted index when options change or dropdown opens
+    React.useEffect(() => {
+        if (open) {
+            const currentIndex = displayOptions.findIndex(opt => opt.value?.toString() === value?.toString());
+            setHighlightedIndex(currentIndex >= 0 ? currentIndex : 0);
+        }
+    }, [open, displayOptions, value]);
+    // When typing narrows list, reset to first result
+    React.useEffect(() => {
+        setHighlightedIndex(0);
+    }, [displayOptions.length]);
+    // Keydown for the searchable single-select input: arrows move the highlight,
+    // Enter commits the highlighted option (Radix can't — focus is in this input).
+    const handleSearchKeyDown = React.useCallback((e) => {
+        if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            e.stopPropagation();
+            setHighlightedIndex(prev => (prev + 1 >= displayOptions.length ? 0 : prev + 1));
+        }
+        else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            e.stopPropagation();
+            setHighlightedIndex(prev => (prev - 1 < 0 ? displayOptions.length - 1 : prev - 1));
+        }
+        else if (e.key === 'Enter' || e.key === 'Tab') {
+            const opt = displayOptions[highlightedIndex];
+            if (opt && !opt.disabled) {
+                e.preventDefault();
+                e.stopPropagation();
+                onValueChange(opt.value);
+                onOpenChange(false);
+            }
+            else if (allowCustomInput && searchTerm.trim()) {
+                e.preventDefault();
+                e.stopPropagation();
+                handleCreateOption();
+            }
+        }
+        else if (e.key === 'Escape') {
+            e.preventDefault();
+            e.stopPropagation();
+            onOpenChange(false);
+        }
+        else {
+            e.stopPropagation();
+        }
+    }, [displayOptions, highlightedIndex, onValueChange, onOpenChange, allowCustomInput, searchTerm, handleCreateOption]);
+    // Handle keyboard navigation - works both when open and closed (like DevExtreme)
+    const handleKeyDown = React.useCallback((e) => {
+        // When dropdown is CLOSED - cycle through options with arrow keys
+        if (!open) {
+            if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+                e.preventDefault();
+                e.stopPropagation();
+                // Use allOptions for closed navigation (not filtered)
+                const options = allOptions.filter(opt => !opt.disabled && opt.value != null && opt.value !== '');
+                if (options.length === 0)
+                    return;
+                // Find current index
+                const currentIndex = options.findIndex(opt => opt.value?.toString() === value?.toString());
+                let newIndex;
+                if (e.key === 'ArrowDown') {
+                    // Move to next option, or first if nothing selected or at end
+                    newIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % options.length;
+                }
+                else {
+                    // Move to previous option, or last if nothing selected or at start
+                    newIndex = currentIndex < 0 ? options.length - 1 : (currentIndex - 1 + options.length) % options.length;
+                }
+                const newOption = options[newIndex];
+                if (newOption) {
+                    onValueChange(newOption.value);
+                }
+                return;
+            }
+            return;
+        }
+        // When dropdown is OPEN - navigate within filtered list
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                if (filteredOptions.length > 0) {
+                    setHighlightedIndex(prev => {
+                        const next = prev + 1;
+                        return next >= filteredOptions.length ? 0 : next;
+                    });
+                }
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                if (filteredOptions.length > 0) {
+                    setHighlightedIndex(prev => {
+                        const next = prev - 1;
+                        return next < 0 ? filteredOptions.length - 1 : next;
+                    });
+                }
+                break;
+            case 'Tab':
+            case 'Enter':
+                e.preventDefault();
+                if (filteredOptions.length > 0) {
+                    // Select highlighted option from list
+                    const selectedOpt = filteredOptions[highlightedIndex];
+                    if (selectedOpt && !selectedOpt.disabled) {
+                        onValueChange(selectedOpt.value);
+                        onOpenChange(false);
+                    }
+                }
+                else if (allowCustomInput && searchTerm.trim()) {
+                    // No matching options but custom input allowed - create custom value
+                    handleCreateOption();
+                }
+                break;
+            case 'Escape':
+                e.preventDefault();
+                onOpenChange(false);
+                break;
+        }
+    }, [open, allOptions, filteredOptions, highlightedIndex, value, onValueChange, onOpenChange, allowCustomInput, searchTerm, handleCreateOption]);
+    // Combobox mode: allowCustomInput uses Popover instead of Radix Select
+    // to avoid Radix's opinionated keyboard handling fighting with custom input
+    const searchInputRef = React.useRef(null);
+    const handleComboKeyDown = React.useCallback((e) => {
+        const validOptions = filteredOptions.filter(o => o.value != null && o.value !== '');
+        if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            setHighlightedIndex(prev => (prev + 1 >= validOptions.length ? 0 : prev + 1));
+        }
+        else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            setHighlightedIndex(prev => (prev - 1 < 0 ? validOptions.length - 1 : prev - 1));
+        }
+        else if (e.key === 'Enter') {
+            e.preventDefault();
+            if (validOptions.length > 0) {
+                const opt = validOptions[highlightedIndex] || validOptions[0];
+                if (opt && !opt.disabled) {
+                    onValueChange(opt.value);
+                    onOpenChange(false);
+                }
+            }
+            else if (searchTerm.trim()) {
+                handleCreateOption();
+            }
+        }
+        else if (e.key === 'Escape') {
+            e.preventDefault();
+            onOpenChange(false);
+        }
+    }, [filteredOptions, highlightedIndex, searchTerm, onValueChange, onOpenChange, handleCreateOption]);
+    if (customTrigger) {
+        return (_jsxs(Popover.Root, { open: open, onOpenChange: onOpenChange, children: [_jsx(Popover.Trigger, { asChild: true, children: customTrigger }), _jsx(Popover.Portal, { container: typeof document !== 'undefined' ? document.body : undefined, children: _jsxs(Popover.Content, { className: cn(getDropdownClassName.content(), "flex flex-col !max-h-72 overflow-hidden", contentClassName), side: "bottom", align: "start", sideOffset: 4, avoidCollisions: true, sticky: "always", collisionPadding: 16, children: [searchable && (_jsx(DropdownSearch, { searchTerm: searchTerm, setSearchTerm: setSearchTerm, resultCount: displayOptions.length, onKeyDown: handleSearchKeyDown })), _jsx("div", { className: dropdownSharedStyles.viewport, onWheel: (e) => e.stopPropagation(), children: loading ? (_jsx("div", { className: "py-6 text-center text-xs text-[rgb(var(--fg-muted))]", children: "Loading..." })) : displayOptions.length === 0 ? (_jsx("div", { className: "py-6 text-center text-xs text-[rgb(var(--fg-muted))]", children: emptyMessage })) : (displayOptions.map((option, index) => (_jsxs("div", { onMouseDown: (e) => { e.preventDefault(); if (!option.disabled) {
+                                        onValueChange(option.value);
+                                        onOpenChange(false);
+                                    } }, onMouseEnter: () => setHighlightedIndex(index), className: cn("relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-xs outline-none transition-colors duration-150", option.value?.toString() === value?.toString()
+                                        ? "bg-[rgb(var(--color-primary)/0.08)] text-[rgb(var(--color-primary))]"
+                                        : index === highlightedIndex ? "bg-[rgb(var(--bg-hover))]" : "hover:bg-[rgb(var(--bg-hover))]", option.disabled && "opacity-50 pointer-events-none"), children: [_jsx("span", { className: "absolute left-2 flex h-3.5 w-3.5 items-center justify-center", children: option.value?.toString() === value?.toString() && _jsx(Check, { className: "h-4 w-4" }) }), _jsxs("div", { className: "min-w-0 flex items-center gap-2", children: [option.image && _jsx(OptionImage, { image: option.image, alt: option.label }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "font-medium truncate", children: option.label }), option.description && _jsx("div", { className: "text-xs text-[rgb(var(--fg-muted))] truncate", children: option.description })] })] })] }, option.key || `${option.value}-${index}`)))) }), customFooter && (_jsx("div", { onPointerDown: (e) => e.stopPropagation(), onMouseDown: (e) => e.stopPropagation(), onClick: (e) => e.stopPropagation(), style: { pointerEvents: 'auto' }, children: customFooter }))] }) })] }));
+    }
+    if (allowCustomInput) {
+        return (_jsxs(Popover.Root, { open: open, onOpenChange: onOpenChange, children: [_jsx(Popover.Trigger, { asChild: true, children: _jsxs("div", { id: id, role: "combobox", "aria-label": ariaLabel, "aria-expanded": open, tabIndex: disabled ? -1 : 0, onKeyDown: (e) => {
+                            if (e.key === 'Enter' || e.key === ' ') {
+                                e.preventDefault();
+                                if (!disabled)
+                                    onOpenChange(!open);
+                            }
+                        }, className: cn("group relative flex items-center justify-between rounded-md border bg-bg-surface cursor-pointer transition-all duration-200", dropdownSharedStyles.trigger.sizes[size], dropdownSharedStyles.trigger.focus, error ? dropdownSharedStyles.trigger.error : dropdownSharedStyles.trigger.normal, autoWidth ? dropdownSharedStyles.trigger.autoWidth : dropdownSharedStyles.trigger.fullWidth, disabled && dropdownSharedStyles.trigger.disabled, triggerClassName, className), children: [_jsx("span", { className: cn("pl-3 flex-1 truncate text-xs", !displayValue && "text-[rgb(var(--fg-subtle))] font-normal"), children: displayValue || placeholder }), _jsxs("div", { className: "flex items-center gap-0.5 pr-2 flex-shrink-0", children: [clearable && value && !disabled && (_jsx(ClearButton, { onClear: handleClear, disabled: disabled })), trailingAction && (
+                                    // Stop bubbling so interacting with the trailing action doesn't
+                                    // toggle the dropdown popover.
+                                    _jsx("div", { className: "flex items-center", onClick: (e) => e.stopPropagation(), onKeyDown: (e) => e.stopPropagation(), children: trailingAction })), _jsx(ChevronDown, { className: cn("h-4 w-4 text-[rgb(var(--fg-muted))] transition-transform duration-200", open && "rotate-180") })] })] }) }), _jsx(Popover.Portal, { container: typeof document !== 'undefined' ? document.body : undefined, children: _jsxs(Popover.Content, { className: cn(getDropdownClassName.content(), "flex flex-col !max-h-72 overflow-hidden"), side: "bottom", align: "start", sideOffset: 4, avoidCollisions: true, sticky: "always", collisionPadding: 16, onOpenAutoFocus: (e) => { e.preventDefault(); setTimeout(() => searchInputRef.current?.focus(), 50); }, children: [_jsx("div", { className: "px-3 py-2 border-b border-[rgb(var(--bd-default))]", children: _jsxs("div", { className: "flex items-center gap-2 px-2 py-1.5 rounded-lg border border-[rgb(var(--bd-default))] bg-[rgb(var(--bg-surface))]", children: [_jsx(Search, { className: "w-3.5 h-3.5 text-[rgb(var(--fg-muted))] flex-shrink-0" }), _jsx("input", { ref: searchInputRef, type: "text", placeholder: "Type to search...", className: "w-full text-xs bg-transparent text-[rgb(var(--fg-default))] placeholder:text-[rgb(var(--fg-muted))] focus:outline-none", value: searchTerm, onChange: (e) => setSearchTerm(e.target.value), onKeyDown: handleComboKeyDown, autoFocus: true }), filteredOptions.length > 0 && (_jsxs("span", { className: "text-[0.625rem] font-medium text-[rgb(var(--fg-muted))] bg-[rgb(var(--bg-subtle))] px-1.5 py-0.5 rounded-md flex-shrink-0 tabular-nums", children: [filteredOptions.filter(o => o.value != null && o.value !== '').length, " results"] })), searchTerm && (_jsx("button", { onMouseDown: (e) => { e.preventDefault(); setSearchTerm(''); searchInputRef.current?.focus(); }, className: "p-0.5 hover:bg-[rgb(var(--bg-hover))] rounded flex-shrink-0", children: _jsx(X, { className: "h-3 w-3 text-[rgb(var(--fg-muted))]" }) }))] }) }), _jsxs("div", { className: dropdownSharedStyles.viewport, onWheel: (e) => e.stopPropagation(), children: [searchTerm.trim() && !filteredOptions.find(o => String(o.label ?? '').toLowerCase() === searchTerm.trim().toLowerCase()) && (_jsxs("button", { type: "button", onMouseDown: (e) => { e.preventDefault(); handleCreateOption(); }, className: dropdownSharedStyles.createButton, children: [_jsx("span", { className: "text-lg", children: "+" }), _jsxs("span", { children: ["Add \"", searchTerm, "\""] })] })), loading ? (_jsx("div", { className: "py-6 text-center text-xs text-[rgb(var(--fg-muted))]", children: "Loading..." })) : filteredOptions.filter(o => o.value != null && o.value !== '').length === 0 && !searchTerm.trim() ? (_jsx("div", { className: "py-6 text-center text-xs text-[rgb(var(--fg-muted))]", children: emptyMessage })) : (filteredOptions.filter(o => o.value != null && o.value !== '').map((option, index) => (_jsxs("div", { onMouseDown: (e) => { e.preventDefault(); if (!option.disabled) {
+                                            onValueChange(option.value);
+                                            onOpenChange(false);
+                                        } }, onMouseEnter: () => setHighlightedIndex(index), className: cn("relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-xs outline-none transition-colors duration-150", option.value?.toString() === value?.toString()
+                                            ? "bg-[rgb(var(--color-primary)/0.08)] text-[rgb(var(--color-primary))]"
+                                            : index === highlightedIndex ? "bg-[rgb(var(--bg-hover))]" : "hover:bg-[rgb(var(--bg-hover))]", option.disabled && "opacity-50 pointer-events-none"), children: [_jsx("span", { className: "absolute left-2 flex h-3.5 w-3.5 items-center justify-center", children: option.value?.toString() === value?.toString() && _jsx(Check, { className: "h-4 w-4" }) }), _jsxs("div", { className: "min-w-0 flex items-center gap-2", children: [option.image && _jsx(OptionImage, { image: option.image, alt: option.label }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "font-medium truncate", children: option.label }), option.description && _jsx("div", { className: "text-xs text-[rgb(var(--fg-muted))] truncate", children: option.description })] })] })] }, option.key || `${option.value}-${index}`))))] })] }) })] }));
+    }
+    return (_jsxs(SelectPrimitive.Root, { value: value != null && value !== '' ? value.toString() : '', onValueChange: (newValue) => onValueChange(newValue), open: open, onOpenChange: onOpenChange, disabled: disabled, children: [_jsx("div", { className: "relative", onKeyDownCapture: handleKeyDown, children: _jsxs(SelectPrimitive.Trigger, { id: id, "aria-label": ariaLabel, suppressHydrationWarning: true, className: cn("group", dropdownSharedStyles.trigger.base, dropdownSharedStyles.trigger.sizes[size], dropdownSharedStyles.trigger.variants[variant], dropdownSharedStyles.trigger.focus, error ? dropdownSharedStyles.trigger.error : dropdownSharedStyles.trigger.normal, autoWidth ? dropdownSharedStyles.trigger.autoWidth : dropdownSharedStyles.trigger.fullWidth, disabled && dropdownSharedStyles.trigger.disabled, "pl-3 py-2 pr-1 [&>span]:line-clamp-1", className, triggerClassName), children: [displayValue ? (_jsxs("div", { className: "flex items-center gap-2 min-w-0 flex-1", children: [selectedOption?.image && (_jsx(OptionImage, { image: selectedOption.image, alt: displayValue })), _jsx("span", { className: "truncate text-xs", children: displayValue })] })) : (_jsx("span", { className: "text-[rgb(var(--fg-subtle))] font-normal text-xs", children: placeholder })), _jsxs("div", { className: "flex items-center gap-0.5 flex-shrink-0 pr-1", children: [clearable && value && (_jsx(ClearButton, { onClear: handleClear, disabled: disabled, className: "flex-shrink-0" })), _jsx(SelectPrimitive.Icon, { asChild: true, children: _jsx("div", { className: "pr-1 pl-0.5", children: _jsx(ChevronDown, { className: "h-4 w-4 text-[rgb(var(--fg-muted))]" }) }) })] })] }) }), _jsx(SelectPrimitive.Portal, { container: typeof document !== 'undefined' ? document.body : undefined, children: _jsxs(SelectPrimitive.Content, { className: getDropdownClassName.content(), position: "popper", side: "bottom", align: "start", sideOffset: 4, avoidCollisions: true, sticky: "always", collisionPadding: 16, children: [searchable && (_jsx(DropdownSearch, { searchTerm: searchTerm, setSearchTerm: setSearchTerm, resultCount: filteredOptions.filter(o => o.value != null && o.value !== '').length })), _jsxs(SelectPrimitive.Viewport, { className: dropdownSharedStyles.viewport, onMouseDown: (e) => {
+                                // Prevent focus from leaving the search input when clicking options
+                                if (searchable)
+                                    e.preventDefault();
+                            }, children: [showCreateOption && effectiveCreateOption && (_jsx("button", { type: "button", onClick: handleCreateOption, disabled: isCreating, className: dropdownSharedStyles.createButton, children: isCreating ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "h-4 w-4 border-2 border-primary border-t-transparent rounded-full animate-spin" }), _jsx("span", { children: "Creating..." })] })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "text-lg", children: "+" }), _jsxs("span", { children: [allowCustomInput ? 'Add' : createOptionLabel, " \"", searchTerm, "\""] })] })) })), loading ? (_jsx("div", { className: "py-6 text-center text-sm text-fg-muted bg-bg-surface", children: "Loading..." })) : filteredOptions.length === 0 && !showCreateOption ? (_jsx("div", { className: "py-6 text-center text-sm text-fg-muted bg-bg-surface", children: emptyMessage })) : ((() => {
+                                    // Performance: cap render count for very large lists. User can still search.
+                                    const RENDER_CAP = 200;
+                                    const cleaned = filteredOptions.filter(option => option.value != null && option.value !== '');
+                                    const visible = cleaned.slice(0, RENDER_CAP);
+                                    const hiddenCount = cleaned.length - visible.length;
+                                    return (_jsxs(_Fragment, { children: [visible.map((option, index) => {
+                                                const isHighlighted = index === highlightedIndex;
+                                                return (_jsxs(SelectPrimitive.Item, { value: String(option.value), disabled: option.disabled, className: cn(getDropdownClassName.item(), isHighlighted && "bg-[rgb(var(--bg-hover))]"), onMouseEnter: () => setHighlightedIndex(index), children: [_jsx("span", { className: "absolute left-2 flex h-3.5 w-3.5 items-center justify-center", children: _jsx(SelectPrimitive.ItemIndicator, { children: _jsx(Check, { className: "h-4 w-4" }) }) }), _jsx(SelectPrimitive.ItemText, { children: _jsxs("div", { className: "min-w-0 flex items-center gap-2", children: [option.image && (_jsx(OptionImage, { image: option.image, alt: option.label })), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "font-medium truncate", children: option.label }), option.description && (_jsx("div", { className: "text-xs text-[rgb(var(--fg-muted))] truncate", children: option.description }))] })] }) })] }, option.key || `${option.value}-${index}`));
+                                            }), hiddenCount > 0 && (_jsxs("div", { className: "py-2 px-3 text-center text-[0.625rem] text-[rgb(var(--fg-muted))] border-t border-[rgb(var(--bd-default))] bg-[rgb(var(--bg-subtle))]", children: ["Showing ", visible.length, " of ", cleaned.length, ". Type to filter."] }))] }));
+                                })())] }), customFooter && (_jsx("div", { onPointerDown: (e) => e.stopPropagation(), onMouseDown: (e) => e.stopPropagation(), onClick: (e) => e.stopPropagation(), style: { pointerEvents: 'auto' }, children: customFooter }))] }) })] }));
+}

package/dist/components/forms/dropdown/hooks/useDropdownCreate.d.ts

@@ -0,0 +1,8 @@
+import { DropdownOption } from '../types.js';
+export declare function useDropdownCreate(allowTextInput: boolean, allowCustomInput: boolean, onCreateOption?: (inputValue: string) => DropdownOption | Promise<DropdownOption>): {
+    createdOptions: DropdownOption[];
+    isCreating: boolean;
+    enableTextInput: boolean;
+    effectiveCreateOption: (inputValue: string) => DropdownOption | Promise<DropdownOption>;
+    handleCreateOption: (searchTerm: string, multiSelect: boolean, value: string | number | string[] | undefined, onValueChange: (value: string | number | string[]) => void, setSearchTerm: (term: string) => void, setOpen: (open: boolean) => void) => Promise<void>;
+};

package/dist/components/forms/dropdown/hooks/useDropdownCreate.js

@@ -0,0 +1,52 @@
+'use client';
+import * as React from 'react';
+export function useDropdownCreate(allowTextInput, allowCustomInput, onCreateOption) {
+    const [createdOptions, setCreatedOptions] = React.useState([]);
+    const [isCreating, setIsCreating] = React.useState(false);
+    // Enable allowTextInput when allowCustomInput is true
+    const enableTextInput = allowTextInput || allowCustomInput;
+    // Auto-create option handler for allowCustomInput mode
+    const autoCreateOption = React.useCallback((inputValue) => {
+        return {
+            value: inputValue,
+            label: inputValue
+        };
+    }, []);
+    // Use provided onCreateOption or auto-create for allowCustomInput
+    const effectiveCreateOption = onCreateOption || (allowCustomInput ? autoCreateOption : undefined);
+    // Handle creating new option
+    const handleCreateOption = React.useCallback(async (searchTerm, multiSelect, value, onValueChange, setSearchTerm, setOpen) => {
+        if (!effectiveCreateOption || !searchTerm.trim() || isCreating)
+            return;
+        setIsCreating(true);
+        try {
+            const newOption = await effectiveCreateOption(searchTerm.trim());
+            setCreatedOptions(prev => [...prev, newOption]);
+            // Auto-select the newly created option
+            if (multiSelect) {
+                const currentValues = Array.isArray(value) ? value.map(v => v.toString()) : [];
+                onValueChange([...currentValues, newOption.value.toString()]);
+            }
+            else {
+                onValueChange(newOption.value);
+            }
+            setSearchTerm('');
+            if (!multiSelect) {
+                setOpen(false);
+            }
+        }
+        catch (error) {
+            console.error('Failed to create option:', error);
+        }
+        finally {
+            setIsCreating(false);
+        }
+    }, [effectiveCreateOption, isCreating]);
+    return {
+        createdOptions,
+        isCreating,
+        enableTextInput,
+        effectiveCreateOption,
+        handleCreateOption
+    };
+}

package/dist/components/forms/dropdown/hooks/useDropdownFiltering.d.ts

@@ -0,0 +1,5 @@
+import { DropdownOption } from '../types.js';
+export declare function useDropdownFiltering(allOptions: DropdownOption[], searchTerm: string, enableTextInput: boolean, pinnedValues?: string[], preserveOrder?: boolean): {
+    filteredOptions: DropdownOption[];
+    showCreateOption: boolean;
+};

package/dist/components/forms/dropdown/hooks/useDropdownFiltering.js

@@ -0,0 +1,51 @@
+'use client';
+import * as React from 'react';
+import { naturalCompare } from '../../../../lib/utils.js';
+export function useDropdownFiltering(allOptions, searchTerm, enableTextInput, 
+// Values pinned to the top of the list (selected-first). Snapshotted at open
+// time by the caller so rows don't jump while the user is ticking.
+pinnedValues, 
+// Keep the caller-supplied option order (e.g. backend priority ordering)
+// instead of natural-sorting by label. Pinned/sentinel rows still float up.
+preserveOrder) {
+    // Filter options based on search term, then natural-sort by label so a
+    // numeric prefix like "10" sorts after "9" instead of after "1". Sentinel
+    // options (None / All / -) are pinned to the top regardless of sort.
+    const filteredOptions = React.useMemo(() => {
+        const base = !searchTerm
+            ? allOptions
+            : allOptions.filter(option => {
+                const term = searchTerm.toLowerCase();
+                return (String(option.label).toLowerCase().includes(term) ||
+                    (option.description && option.description.toLowerCase().includes(term)));
+            });
+        const isSentinel = (label) => {
+            const l = String(label ?? '').trim().toLowerCase();
+            return l === 'none' || l === 'all' || l === '-' || l === '' || l === 'n/a' || l === 'na';
+        };
+        const pinned = pinnedValues && pinnedValues.length > 0 ? new Set(pinnedValues.map(String)) : null;
+        return [...base].sort((a, b) => {
+            if (pinned) {
+                const pa = pinned.has(String(a.value)), pb = pinned.has(String(b.value));
+                if (pa !== pb)
+                    return pa ? -1 : 1;
+            }
+            const sa = isSentinel(a.label), sb = isSentinel(b.label);
+            if (sa !== sb)
+                return sa ? -1 : 1;
+            return preserveOrder ? 0 : naturalCompare(a.label, b.label);
+        });
+    }, [allOptions, searchTerm, pinnedValues, preserveOrder]);
+    // Check if we should show "Create" option
+    const showCreateOption = React.useMemo(() => {
+        if (!enableTextInput || !searchTerm.trim())
+            return false;
+        const term = searchTerm.toLowerCase();
+        const exactMatch = allOptions.some(opt => String(opt.label).toLowerCase() === term);
+        return !exactMatch;
+    }, [enableTextInput, searchTerm, allOptions]);
+    return {
+        filteredOptions,
+        showCreateOption
+    };
+}

package/dist/components/forms/dropdown/hooks/useDropdownState.d.ts

@@ -0,0 +1,7 @@
+import { DropdownOption } from '../types.js';
+export declare function useDropdownState(value: string | number | string[] | undefined, multiSelect: boolean, options: DropdownOption[], createdOptions: DropdownOption[]): {
+    allOptions: DropdownOption[];
+    selectedValues: string[];
+    selectedOptions: DropdownOption[];
+    selectedOption: DropdownOption;
+};

package/dist/components/forms/dropdown/hooks/useDropdownState.js

@@ -0,0 +1,27 @@
+'use client';
+import * as React from 'react';
+export function useDropdownState(value, multiSelect, options, createdOptions) {
+    // Combine created options with provided options
+    const allOptions = React.useMemo(() => {
+        return [...createdOptions, ...options];
+    }, [createdOptions, options]);
+    // Handle both single and multi-select values
+    const selectedValues = React.useMemo(() => {
+        if (multiSelect) {
+            return Array.isArray(value) ? value.map(v => v.toString()) : [];
+        }
+        return value ? [value.toString()] : [];
+    }, [value, multiSelect]);
+    const selectedOptions = React.useMemo(() => {
+        return allOptions.filter(option => option.value != null && selectedValues.includes(option.value.toString()));
+    }, [allOptions, selectedValues]);
+    const selectedOption = React.useMemo(() => {
+        return allOptions.find(option => option.value != null && option.value.toString() === value?.toString());
+    }, [allOptions, value]);
+    return {
+        allOptions,
+        selectedValues,
+        selectedOptions,
+        selectedOption
+    };
+}

package/dist/components/forms/dropdown/index.d.ts

@@ -0,0 +1,2 @@
+export { Dropdown } from './Dropdown.js';
+export type { DropdownProps, DropdownOption } from './types.js';

package/dist/components/forms/dropdown/index.js

@@ -0,0 +1,2 @@
+'use client';
+export { Dropdown } from './Dropdown.js';

package/dist/components/forms/dropdown/types.d.ts

@@ -0,0 +1,67 @@
+export interface DropdownOption {
+    value: string | number;
+    label: string;
+    disabled?: boolean;
+    description?: string;
+    key?: string;
+    image?: string;
+}
+export interface DropdownProps {
+    options: DropdownOption[];
+    value?: string | number | string[];
+    placeholder?: string;
+    onValueChange: (value: string | number | string[]) => void;
+    onOpen?: () => void;
+    disabled?: boolean;
+    loading?: boolean;
+    searchable?: boolean;
+    clearable?: boolean;
+    className?: string;
+    error?: boolean | string;
+    label?: React.ReactNode;
+    labelExtra?: React.ReactNode;
+    required?: boolean;
+    emptyMessage?: string;
+    triggerClassName?: string;
+    /** Forwarded to the trigger so a <label htmlFor> can target it. */
+    id?: string;
+    /** Accessible name for the trigger when no visible label is rendered. */
+    'aria-label'?: string;
+    autoWidth?: boolean;
+    customFooter?: React.ReactNode;
+    multiSelect?: boolean;
+    maxSelections?: number;
+    showSelectedCount?: boolean;
+    showAsTags?: boolean;
+    /** Custom text for the multi-select trigger count, e.g. (n) => `${n} quantities selected` */
+    formatSelectedCount?: (count: number) => string;
+    allowTextInput?: boolean;
+    onCreateOption?: (inputValue: string) => DropdownOption | Promise<DropdownOption>;
+    createOptionLabel?: string;
+    allowCustomValues?: boolean;
+    allowCustomInput?: boolean;
+    trackEdits?: boolean;
+    originalValue?: string | number | string[];
+    isEdited?: boolean;
+    variant?: 'default' | 'compact' | 'detailed';
+    size?: 'sm' | 'md' | 'lg';
+    contentClassName?: string;
+    /** Header title for select all section */
+    selectAllLabel?: string;
+    /** Hide the Select All / Deselect All header row */
+    hideSelectAll?: boolean;
+    /** Show "ONLY" button on hover (like OTIF) */
+    showOnlyButton?: boolean;
+    /** Custom trigger element - replaces default trigger button */
+    customTrigger?: React.ReactNode;
+    /** Keep the caller-supplied option order (e.g. backend priority ordering) instead of label-sorting. */
+    preserveOrder?: boolean;
+    /**
+     * Element rendered inside the trigger, between the clear button and the chevron.
+     * Use for inline action buttons (e.g. a group-picker popover, an "open in modal"
+     * shortcut) that should sit visually attached to the field rather than as a
+     * separate adjacent control. Click events from this element are isolated —
+     * they will not toggle the dropdown.
+     */
+    trailingAction?: React.ReactNode;
+}

package/dist/components/forms/dropdown/types.js

@@ -0,0 +1,2 @@
+'use client';
+export {};

package/dist/components/forms/file-attachment/EmailPreview.d.ts

@@ -0,0 +1,5 @@
+import * as React from 'react';
+import type { AttachedFile } from './FileAttachment.js';
+export declare function EmailPreview({ file }: {
+    file: AttachedFile;
+}): React.JSX.Element;