flikkui 0.2.0-beta.2 → 0.2.0-beta.5

package/dist/components/forms/Select/Select.d.ts

@@ -1,18 +1,117 @@
 import React from "react";
-import type { SelectProps, SelectButtonProps, SelectOptionsProps, SelectOptionProps } from "./Select.types";
+import type { SelectProps, SelectButtonProps, SelectOptionsProps, SelectOptionProps, SelectState, SelectSize, SelectThemeOverrides } from "./Select.types";
+import { useSelectState, type UseSelectStateReturn, type UseSelectStateProps } from "./useSelectState";
+/**
+ * Context value type for Select components
+ * Extends UseSelectStateReturn with additional component-specific properties
+ */
+export interface SelectContextValue<T = any> extends UseSelectStateReturn<T> {
+    /** Size variant */
+    size: SelectSize;
+    /** Component state (default, disabled) */
+    state: SelectState;
+    /** Theme configuration */
+    theme: SelectThemeOverrides;
+    /** Whether search is enabled */
+    searchable: boolean;
+    /** Whether typeahead is enabled */
+    enableTypeahead: boolean;
+    /** Button ref (alias for triggerRef for backward compatibility) */
+    buttonRef: React.MutableRefObject<HTMLButtonElement | null>;
+}
+/**
+ * SelectContext - exported for external consumption
+ */
+export declare const SelectContext: React.Context<SelectContextValue<any> | undefined>;
+/**
+ * useSelectContext - Hook to consume SelectContext
+ * Throws if used outside of SelectProvider
+ */
+export declare const useSelectContext: <T = any>() => SelectContextValue<T>;
+/**
+ * Props for the SelectProvider component
+ */
+export interface SelectProviderProps<T = any> {
+    /** Child components */
+    children: React.ReactNode;
+    /** State from useSelectState hook */
+    selectState: UseSelectStateReturn<T>;
+    /** Size variant */
+    size?: SelectSize;
+    /** Component state */
+    componentState?: SelectState;
+    /** Theme overrides */
+    theme?: SelectThemeOverrides;
+    /** Whether search is enabled */
+    searchable?: boolean;
+    /** Whether typeahead is enabled */
+    enableTypeahead?: boolean;
+}
+/**
+ * SelectProvider - Provides select context to children
+ *
+ * This component allows building custom dropdown components using Select primitives.
+ *
+ * @example
+ * ```tsx
+ * const selectState = useSelectState({ options, value, onChange });
+ *
+ * <SelectProvider selectState={selectState} size="md">
+ *   <MyCustomTrigger />
+ *   <SelectOptions isOpen={selectState.isOpen}>
+ *     {selectState.filteredOptions.map(option => (
+ *       <SelectOption key={option.id} value={option.value}>
+ *         {option.label}
+ *       </SelectOption>
+ *     ))}
+ *   </SelectOptions>
+ * </SelectProvider>
+ * ```
+ */
+export declare function SelectProvider<T = any>({ children, selectState, size, componentState, theme: themeOverrides, searchable, enableTypeahead, }: SelectProviderProps<T>): React.JSX.Element;
 /**
  * Select Button Component
  */
 export declare const SelectButton: React.FC<SelectButtonProps>;
+/**
+ * Extended props for SelectOptions to support custom triggers
+ */
+export interface SelectOptionsExtendedProps extends SelectOptionsProps {
+    /** Custom trigger ref - if provided, uses this instead of buttonRef from context */
+    triggerRef?: React.RefObject<HTMLElement>;
+}
 /**
  * Select Options Component
  */
-export declare const SelectOptions: React.FC<SelectOptionsProps>;
+export declare const SelectOptions: React.FC<SelectOptionsExtendedProps>;
 /**
  * Select Option Component
  */
 export declare const SelectOption: <T extends any>({ value, isSelected, disabled, className, onSelect, children, }: SelectOptionProps<T>) => React.JSX.Element;
 /**
  * Main Select Component
+ *
+ * A fully-featured select/dropdown component with support for:
+ * - Keyboard navigation
+ * - Search/filtering
+ * - Typeahead
+ * - Creatable options
+ * - Portal rendering
+ * - Custom theming
+ *
+ * @example
+ * ```tsx
+ * <Select
+ *   options={[
+ *     { id: "1", label: "Option 1", value: "option1" },
+ *     { id: "2", label: "Option 2", value: "option2" },
+ *   ]}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   placeholder="Select an option"
+ * />
+ * ```
  */
 export declare const Select: <T extends any>({ id, name, size, state, value, displayValue, placeholder, disabled, required, options, label, helperText, onChange, onFocus, onBlur, iconStart, iconEnd, theme: themeOverrides, className, wrapperClassName, searchable, searchPlaceholder, portal, placement, offset, enableTypeahead, creatable, onCreateOption, createLabel, children, }: SelectProps<T>) => React.JSX.Element;
+export { useSelectState };
+export type { UseSelectStateProps, UseSelectStateReturn };

package/dist/components/forms/Select/Select.js

@@ -1,4 +1,4 @@
-import React__default, { createContext, useState, useRef, useEffect, useContext } from 'react';
+import React__default, { createContext, useRef, useCallback, useEffect, useContext } from 'react';
 import { AnimatePresence, motion } from 'motion/react';
 import { createPortal } from 'react-dom';
 import { selectTheme } from './Select.theme.js';
@@ -10,13 +10,17 @@ import { ChevronUpDownIcon } from '../../../icons/core/ChevronUpDown.js';
 import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { cn } from '../../../utils/cn.js';
 import { isValidTypeaheadChar, findNextMatchingOption, TYPEAHEAD_TIMEOUT_MS } from '../../../utils/typeaheadUtils.js';
-import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
+import { PlusIcon, MagnifyingGlassIcon } from '@heroicons/react/24/outline';
+import { useSelectState } from './useSelectState.js';
 
+// ============================================================================
+// Dark Mode Hook
+// ============================================================================
 /**
  * Hook to detect dark mode state from document
  */
 const useDarkMode = () => {
-    const [isDark, setIsDark] = useState(false);
+    const [isDark, setIsDark] = React__default.useState(false);
     useEffect(() => {
         if (typeof document === "undefined")
             return;
@@ -41,14 +45,60 @@ const useDarkMode = () => {
     }, []);
     return isDark;
 };
+/**
+ * SelectContext - exported for external consumption
+ */
 const SelectContext = createContext(undefined);
+/**
+ * useSelectContext - Hook to consume SelectContext
+ * Throws if used outside of SelectProvider
+ */
 const useSelectContext = () => {
     const context = useContext(SelectContext);
     if (!context) {
-        throw new Error("Select components must be used within a SelectContainer");
+        throw new Error("Select components must be used within a SelectProvider");
     }
     return context;
 };
+/**
+ * SelectProvider - Provides select context to children
+ *
+ * This component allows building custom dropdown components using Select primitives.
+ *
+ * @example
+ * ```tsx
+ * const selectState = useSelectState({ options, value, onChange });
+ *
+ * <SelectProvider selectState={selectState} size="md">
+ *   <MyCustomTrigger />
+ *   <SelectOptions isOpen={selectState.isOpen}>
+ *     {selectState.filteredOptions.map(option => (
+ *       <SelectOption key={option.id} value={option.value}>
+ *         {option.label}
+ *       </SelectOption>
+ *     ))}
+ *   </SelectOptions>
+ * </SelectProvider>
+ * ```
+ */
+function SelectProvider({ children, selectState, size = "md", componentState = "default", theme: themeOverrides, searchable = false, enableTypeahead = true, }) {
+    const theme = { ...selectTheme, ...(themeOverrides || {}) };
+    // Cast triggerRef to buttonRef for backward compatibility
+    const buttonRef = selectState.triggerRef;
+    const contextValue = {
+        ...selectState,
+        size,
+        state: componentState,
+        theme,
+        searchable,
+        enableTypeahead,
+        buttonRef,
+    };
+    return (React__default.createElement(SelectContext.Provider, { value: contextValue }, children));
+}
+// ============================================================================
+// SelectButton Component
+// ============================================================================
 /**
  * Select Button Component
  */
@@ -72,7 +122,8 @@ const SelectButton = ({ id, disabled, isOpen, state = "default", size = "md", ic
             "outline-2 outline-[var(--color-primary)] -outline-offset-1 ring-4 ring-[var(--color-primary)]/10"
         : "";
     return (React__default.createElement("div", { className: cn(buttonWrapperStyle) },
-        React__default.createElement("button", { ref: buttonRef, id: id, type: "button", className: cn(baseStyle, sizeStyle, stateStyle, hoverStateStyle, activeFocusState, iconStartPadding, iconEndPadding, buttonStyle, className), onClick: onClick, onFocus: onFocus, onBlur: onBlur, disabled: disabled, "aria-expanded": isOpen, "aria-haspopup": "listbox" },
+        React__default.createElement("button", { ref: buttonRef, id: id, type: "button", className: cn(baseStyle, sizeStyle, stateStyle, hoverStateStyle, activeFocusState, iconStartPadding, iconEndPadding, buttonStyle, className // User overrides take highest precedence
+            ), onClick: onClick, onFocus: onFocus, onBlur: onBlur, disabled: disabled, "aria-expanded": isOpen, "aria-haspopup": "listbox" },
             iconStart && React__default.createElement("span", { className: iconStartStyle }, iconStart),
             children,
             iconEnd && React__default.createElement("span", { className: iconEndStyle }, iconEnd))));
@@ -80,17 +131,19 @@ const SelectButton = ({ id, disabled, isOpen, state = "default", size = "md", ic
 /**
  * Select Options Component
  */
-const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, children, portal = true, placement = "bottom-start", offset = 4, }) => {
+const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, children, portal = true, placement = "bottom-start", offset = 4, triggerRef: customTriggerRef, }) => {
     var _a;
-    const { optionsRef, buttonRef, highlightedIndex, setHighlightedIndex, options, filteredOptions, searchable, searchValue, setSearchValue, enableTypeahead, typeaheadValue, setTypeaheadValue, typeaheadTimeoutRef, theme, } = useSelectContext();
+    const context = useSelectContext();
+    const { optionsRef, buttonRef, highlightedIndex, setHighlightedIndex, filteredOptions, searchable, searchValue, setSearchValue, enableTypeahead, typeaheadValue, setTypeaheadValue, typeaheadTimeoutRef, theme, selectOption, } = context;
+    // Use custom triggerRef if provided, otherwise fall back to buttonRef
+    const effectiveTriggerRef = customTriggerRef || buttonRef;
     // Detect dark mode for portal content
     const isDarkMode = useDarkMode();
     const searchInputRef = useRef(null);
     // Use enhanced dropdown positioning hook with direction-aware animations
-    // Pass trigger width so dropdown matches trigger size
-    const triggerWidth = ((_a = buttonRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect().width) || 0;
+    const triggerWidth = ((_a = effectiveTriggerRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect().width) || 0;
     const { position, cssVariables, contentRef, isFlipped } = useSelectPortal({
-        triggerRef: buttonRef,
+        triggerRef: effectiveTriggerRef,
         isOpen: isOpen || false,
         placement,
         offset,
@@ -103,7 +156,7 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
     // Convert maxHeight to a valid CSS value
     const maxHeightValue = typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight;
     // Combine refs for portal and legacy usage
-    const combinedRef = React__default.useCallback((el) => {
+    const combinedRef = useCallback((el) => {
         if (optionsRef &&
             typeof optionsRef === "object" &&
             "current" in optionsRef) {
@@ -126,8 +179,8 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
                 : optionsRef.current;
             if (currentContentRef &&
                 !currentContentRef.contains(event.target) &&
-                buttonRef.current &&
-                !buttonRef.current.contains(event.target)) {
+                effectiveTriggerRef.current &&
+                !effectiveTriggerRef.current.contains(event.target)) {
                 onClose === null || onClose === void 0 ? void 0 : onClose();
             }
         };
@@ -135,7 +188,7 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
         return () => {
             document.removeEventListener("mousedown", handleClickOutside);
         };
-    }, [isOpen, onClose, optionsRef, buttonRef, contentRef, portal]);
+    }, [isOpen, onClose, optionsRef, effectiveTriggerRef, contentRef, portal]);
     // Handle keyboard navigation
     useEffect(() => {
         if (!isOpen)
@@ -203,9 +256,8 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
                     highlightedIndex < filteredOptions.length) {
                     const highlightedOption = filteredOptions[highlightedIndex];
                     if (!highlightedOption.disabled) {
-                        const { value } = highlightedOption;
-                        const context = useSelectContext();
-                        context.selectOption(value);
+                        const isCreateAction = highlightedOption.id === "__create__";
+                        selectOption(highlightedOption.value, isCreateAction);
                         onClose === null || onClose === void 0 ? void 0 : onClose();
                     }
                 }
@@ -226,25 +278,7 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
         setTypeaheadValue,
         typeaheadTimeoutRef,
         optionsRef,
-    ]);
-    // Reset search and highlighted index when closing
-    useEffect(() => {
-        if (!isOpen) {
-            setSearchValue("");
-            setHighlightedIndex(-1);
-            setTypeaheadValue("");
-            // Clear any pending typeahead timeout
-            if (typeaheadTimeoutRef.current) {
-                clearTimeout(typeaheadTimeoutRef.current);
-                typeaheadTimeoutRef.current = null;
-            }
-        }
-    }, [
-        isOpen,
-        setSearchValue,
-        setHighlightedIndex,
-        setTypeaheadValue,
-        typeaheadTimeoutRef,
+        selectOption,
     ]);
     // Autofocus search input on open for searchable selects
     useEffect(() => {
@@ -282,10 +316,10 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
                     maxHeight: searchable ? "none" : maxHeightValue,
                 }),
         }, role: "listbox", tabIndex: -1, variants: animations, initial: "initial", animate: "visible", exit: "exit" },
-        searchable && (React__default.createElement("div", { className: `sticky top-0 py-1 bg-white z-[10000] border-b border-[var(--color-border)] ${searchInputStyle}`, style: {
+        searchable && (React__default.createElement("div", { className: `sticky top-0 py-1 bg-white dark:bg-[var(--color-background-secondary)] z-[10000] border-b border-[var(--color-border)] ${searchInputStyle}`, style: {
                 "--form-rounded": "0",
             } },
-            React__default.createElement(Input, { placeholder: "Search...", value: searchValue, onChange: handleSearchChange, type: "search", ref: searchInputRef, className: "w-full block bg-white border-none outline-none !min-h-8 py-2 ring-0 shadow-none [&:focus]:outline-none [&:focus]:ring-0 [&:focus]:border-none [&:focus-visible]:outline-none [&:focus-visible]:ring-0 [&:focus-visible]:border-none", iconStart: React__default.createElement(MagnifyingGlassIcon, { strokeWidth: 2, className: "size-4 text-[var(--color-text-muted)] group-focus-within:text-[var(--color-primary)]" }), wrapperClassName: "!border-none !outline-none !ring-0 !shadow-none", inputGroupClassName: "!border-none !outline-none !ring-0 !shadow-none flex items-center", style: {
+            React__default.createElement(Input, { placeholder: "Search...", value: searchValue, onChange: handleSearchChange, type: "search", ref: searchInputRef, className: "w-full block bg-white dark:bg-[var(--color-background-secondary)] border-none outline-none !min-h-8 py-2 ring-0 shadow-none [&:focus]:outline-none [&:focus]:ring-0 [&:focus]:border-none [&:focus-visible]:outline-none [&:focus-visible]:ring-0 [&:focus-visible]:border-none", iconStart: React__default.createElement(MagnifyingGlassIcon, { strokeWidth: 2, className: "size-4 text-[var(--color-text-muted)] group-focus-within:text-[var(--color-primary)] dark:group-focus-within:text-white" }), wrapperClassName: "!border-none !outline-none !ring-0 !shadow-none", inputGroupClassName: "!border-none !outline-none !ring-0 !shadow-none flex items-center", style: {
                     border: "none",
                     outline: "none",
                     boxShadow: "none",
@@ -297,15 +331,20 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
     }
     return optionsContent;
 };
+// ============================================================================
+// SelectOption Component
+// ============================================================================
 /**
  * Select Option Component
  */
 const SelectOption = ({ value, isSelected, disabled, className = "", onSelect, children, }) => {
     var _a;
-    const { highlightedIndex, setHighlightedIndex, options, filteredOptions, theme, selectOption, } = useSelectContext();
+    const { highlightedIndex, setHighlightedIndex, filteredOptions, theme, selectOption, } = useSelectContext();
     const optionStyle = theme.optionStyle || "";
     const selectedOptionStyle = theme.selectedOptionStyle || "";
     const disabledOptionStyle = theme.disabledOptionStyle || "";
+    const highlightedOptionStyle = theme.highlightedOptionStyle || "";
+    const createOptionStyleTheme = theme.createOptionStyle || "";
     // Find index of this option in filteredOptions (not options, to support create option)
     const optionIndex = filteredOptions.findIndex((option) => option.value === value);
     const isHighlighted = optionIndex === highlightedIndex;
@@ -320,78 +359,58 @@ const SelectOption = ({ value, isSelected, disabled, className = "", onSelect, c
         }
     };
     // Apply the hover style directly when keyboard navigating
-    const keyboardHighlightStyle = isHighlighted
-        ? "text-[var(--color-primary)] bg-[var(--color-primary-50)]/50"
-        : "";
+    const keyboardHighlightStyle = isHighlighted ? highlightedOptionStyle : "";
     // Style create option differently
-    const createOptionStyle = isCreateOption
-        ? "font-medium text-[var(--color-primary)]"
-        : "";
-    return (React__default.createElement("div", { className: cn(optionStyle, isSelected && selectedOptionStyle, disabled && disabledOptionStyle, keyboardHighlightStyle, createOptionStyle, className), role: "option", "aria-selected": isSelected, "aria-disabled": disabled, "data-option-index": optionIndex, onMouseEnter: () => !disabled && setHighlightedIndex(optionIndex), onClick: handleClick }, children));
+    const createOptionStyle = isCreateOption ? createOptionStyleTheme : "";
+    return (React__default.createElement("div", { className: cn(optionStyle, isSelected && selectedOptionStyle, disabled && disabledOptionStyle, keyboardHighlightStyle, createOptionStyle, className // User overrides take highest precedence
+        ), role: "option", "aria-selected": isSelected, "aria-disabled": disabled, "data-option-index": optionIndex, onMouseEnter: () => !disabled && setHighlightedIndex(optionIndex), onClick: handleClick }, children));
 };
+// ============================================================================
+// Main Select Component
+// ============================================================================
 /**
  * Main Select Component
+ *
+ * A fully-featured select/dropdown component with support for:
+ * - Keyboard navigation
+ * - Search/filtering
+ * - Typeahead
+ * - Creatable options
+ * - Portal rendering
+ * - Custom theming
+ *
+ * @example
+ * ```tsx
+ * <Select
+ *   options={[
+ *     { id: "1", label: "Option 1", value: "option1" },
+ *     { id: "2", label: "Option 2", value: "option2" },
+ *   ]}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   placeholder="Select an option"
+ * />
+ * ```
  */
 const Select = ({ id, name, size = "md", state = "default", value, displayValue, placeholder = "Select an option", disabled = false, required = false, options = [], label, helperText, onChange, onFocus, onBlur, iconStart, iconEnd, theme: themeOverrides, className = "", wrapperClassName = "", searchable = false, searchPlaceholder = "Search options...", portal = true, placement = "bottom-start", offset = 8, enableTypeahead = true, creatable = false, onCreateOption, createLabel, children, }) => {
     var _a;
     // Merge theme with overrides
     const theme = { ...selectTheme, ...(themeOverrides || {}) };
-    // State
-    const [isOpen, setIsOpen] = useState(false);
-    const [selectedValue, setSelectedValue] = useState(value);
-    const [highlightedIndex, setHighlightedIndex] = useState(-1);
-    const [searchValue, setSearchValue] = useState("");
-    // Typeahead state
-    const [typeaheadValue, setTypeaheadValue] = useState("");
-    const typeaheadTimeoutRef = useRef(null);
-    // Refs
-    const buttonRef = useRef(null);
-    const optionsRef = useRef(null);
-    // Update internal state when prop value changes
-    useEffect(() => {
-        setSelectedValue(value);
-    }, [value]);
-    // Get display value for the selected option
-    const getOptionByValue = (searchValue) => {
-        return options.find((option) => option.value === searchValue);
-    };
-    // Filter options based on search query
-    const baseFilteredOptions = searchValue
-        ? options.filter((option) => option.label.toLowerCase().includes(searchValue.toLowerCase()))
-        : options;
-    // Check if we should show the create option
-    const shouldShowCreateOption = creatable &&
-        searchable &&
-        searchValue.trim() !== "" &&
-        !baseFilteredOptions.some((option) => option.label.toLowerCase() === searchValue.toLowerCase());
-    // Add create option if needed
-    const filteredOptions = shouldShowCreateOption
-        ? [
-            {
-                id: "__create__",
-                label: typeof createLabel === "function"
-                    ? createLabel(searchValue)
-                    : createLabel || `Create "${searchValue}"`,
-                value: searchValue,
-            },
-            ...baseFilteredOptions,
-        ]
-        : baseFilteredOptions;
-    const selectedOption = getOptionByValue(selectedValue);
+    // Use the extracted state hook
+    const selectState = useSelectState({
+        options,
+        value,
+        onChange,
+        searchable,
+        creatable,
+        onCreateOption,
+        createLabel,
+        enableTypeahead,
+    });
+    const { isOpen, setIsOpen, selectedValue, filteredOptions, selectedOption, } = selectState;
+    // Cast triggerRef to buttonRef type
+    selectState.triggerRef;
     const computedDisplayValue = displayValue || (selectedOption ? selectedOption.label : placeholder);
-    // Function to select an option
-    const selectOption = (newValue, isCreateAction = false) => {
-        if (isCreateAction && onCreateOption) {
-            // Call onCreateOption callback if provided
-            onCreateOption(String(newValue));
-        }
-        if (newValue !== selectedValue) {
-            setSelectedValue(newValue);
-            onChange === null || onChange === void 0 ? void 0 : onChange(newValue);
-        }
-        setIsOpen(false);
-        setSearchValue(""); // Clear search value after selection
-    };
     // Button click handler
     const handleButtonClick = () => {
         if (!disabled) {
@@ -407,34 +426,7 @@ const Select = ({ id, name, size = "md", state = "default", value, displayValue,
     const defaultChevronIcon = React__default.createElement(ChevronUpDownIcon, { size: 16, className: "" });
     // Generate a unique ID if not provided
     const selectId = id || `select-${Math.random().toString(36).substring(2, 9)}`;
-    return (React__default.createElement(SelectContext.Provider, { value: {
-            isOpen,
-            setIsOpen,
-            selectedValue,
-            setSelectedValue,
-            highlightedIndex,
-            setHighlightedIndex,
-            options,
-            filteredOptions,
-            searchValue,
-            setSearchValue,
-            getOptionByValue,
-            selectOption,
-            size,
-            state,
-            theme,
-            searchable,
-            enableTypeahead,
-            typeaheadValue,
-            setTypeaheadValue,
-            typeaheadTimeoutRef,
-            buttonRef,
-            optionsRef,
-            creatable,
-            createLabel,
-            onCreateOption,
-            hasCreateOption: shouldShowCreateOption,
-        } },
+    return (React__default.createElement(SelectProvider, { selectState: selectState, size: size, componentState: state, theme: themeOverrides, searchable: searchable, enableTypeahead: enableTypeahead },
         React__default.createElement("div", { className: cn("relative", containerStyle, wrapperClassName) },
             label && (React__default.createElement(FormLabel, { htmlFor: selectId, required: required }, label)),
             React__default.createElement(SelectButton, { id: selectId, disabled: disabled, isOpen: isOpen, state: state, size: size, iconStart: iconStart, iconEnd: iconEnd || defaultChevronIcon, onClick: handleButtonClick, onFocus: onFocus, onBlur: onBlur, className: className },
@@ -442,10 +434,14 @@ const Select = ({ id, name, size = "md", state = "default", value, displayValue,
                         ? theme.valueTextStyle
                         : theme.placeholderTextStyle) }, computedDisplayValue)),
             React__default.createElement(SelectOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), portal: portal, placement: placement, offset: offset }, children ||
-                filteredOptions.map((option) => (React__default.createElement(SelectOption, { key: option.id, value: option.value, isSelected: option.value === selectedValue, disabled: option.disabled || false },
-                    React__default.createElement("span", { className: "block truncate" }, option.label))))),
+                filteredOptions.map((option) => {
+                    const isCreateOption = option.id === "__create__";
+                    return (React__default.createElement(SelectOption, { key: option.id, value: option.value, isSelected: option.value === selectedValue, disabled: option.disabled || false }, isCreateOption ? (React__default.createElement("span", { className: "flex items-center gap-2" },
+                        React__default.createElement(PlusIcon, { className: "size-4 shrink-0" }),
+                        React__default.createElement("span", { className: "block truncate" }, option.label))) : (React__default.createElement("span", { className: "block truncate" }, option.label))));
+                })),
             helperText && (React__default.createElement("p", { className: cn(helperTextStyle, helperTextStateStyle) }, helperText)),
             name && (React__default.createElement("input", { type: "hidden", name: name, value: selectedValue !== undefined ? String(selectedValue) : "" })))));
 };
 
-export { Select, SelectButton, SelectOption, SelectOptions };
+export { Select, SelectButton, SelectContext, SelectOption, SelectOptions, SelectProvider, useSelectContext, useSelectState };

package/dist/components/forms/Select/Select.theme.js

@@ -14,7 +14,7 @@ const selectTheme = {
     // Button style - bg-white for light mode only; dark mode bg comes from baseStyle (inputGroupBaseStyle)
     buttonStyle: "w-full cursor-pointer bg-white dark:bg-[var(--color-neutral-900)]",
     // Placeholder text style - matches Input placeholder styling
-    placeholderTextStyle: "text-[var(--color-text-placeholder)] dark:text-[var(--color-neutral-500)]",
+    placeholderTextStyle: formsBaseTheme.placeholderStyle,
     // Selected value text style
     valueTextStyle: "text-[var(--color-text-primary)] dark:text-[var(--color-neutral-200)]",
     // Size variants - composed from atomic tokens
@@ -31,27 +31,23 @@ const selectTheme = {
     hoverStates: formsBaseTheme.hoverStates,
     // Options container style - Uses position: fixed for proper scroll behavior with standardized z-index
     // Width is controlled by trigger size via estimatedWidth parameter
-    optionsContainerStyle: "fixed z-[1000] max-h-[var(--select-content-available-height,20rem)] overflow-auto overscroll-contain " +
-        "rounded-[var(--form-rounded)] bg-[var(--color-background)]/90 backdrop-blur-md py-0 text-sm " +
-        "shadow-real-lg ring-1 ring-slate-200 focus:outline-none " +
-        "dark:bg-[var(--color-neutral-900)]/90 dark:ring-[var(--color-neutral-700)]",
+    optionsContainerStyle: formsBaseTheme.dropdownStyles.container + " py-0 border border-[var(--color-border)]",
     // Search input style
     searchInputStyle: "group",
     // Individual option style
-    optionStyle: "relative cursor-pointer select-none py-2 px-3 text-[var(--color-text-primary)] " +
-        "hover:text-[var(--color-primary)] hover:bg-[var(--color-primary-50)]/50 " +
-        "dark:text-[var(--color-neutral-200)] dark:hover:text-[var(--color-primary-400)] dark:hover:bg-[var(--color-primary-900)]/50",
+    optionStyle: formsBaseTheme.dropdownStyles.option,
     // Selected option style
-    selectedOptionStyle: "font-medium text-[var(--color-primary)] dark:text-[var(--color-primary-400)]",
+    selectedOptionStyle: formsBaseTheme.dropdownStyles.optionSelected,
+    // Highlighted option style (keyboard navigation)
+    highlightedOptionStyle: formsBaseTheme.dropdownStyles.optionHighlighted,
     // Disabled option style
-    disabledOptionStyle: "cursor-not-allowed opacity-50 hover:bg-transparent hover:text-[var(--color-text-primary)]",
+    disabledOptionStyle: formsBaseTheme.dropdownStyles.optionDisabled,
+    // Create option style
+    createOptionStyle: formsBaseTheme.dropdownStyles.optionCreate,
     // Helper text style - inherited from common form theme
     helperTextStyle: formsBaseTheme.helperText,
     // Helper text state variants
-    helperTextStates: {
-        default: "text-[var(--color-text-muted)] dark:text-[var(--color-neutral-400)]",
-        disabled: "text-[var(--color-text-disabled)] dark:text-[var(--color-neutral-600)]",
-    },
+    helperTextStates: formsBaseTheme.helperTextStates,
     // Left icon style - inherited from common form theme
     iconStartStyle: formsBaseTheme.iconStyles.left,
     // Right icon style - inherited from common form theme

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

@@ -37,7 +37,7 @@ export interface SelectProps<T = any> extends SelectBaseProps {
     /** Currently selected option */
     value?: T;
     /** Custom display value to show in trigger (overrides selected option label) */
-    displayValue?: string;
+    displayValue?: React.ReactNode;
     /** Placeholder text when no option is selected */
     placeholder?: string;
     /** Whether the select is disabled */
@@ -147,7 +147,7 @@ export interface SelectOptionProps<T = any> extends SelectBaseProps {
     children?: React.ReactNode;
 }
 export type SelectSize = "sm" | "md" | "lg";
-export type SelectState = "default" | "disabled";
+export type SelectState = "default" | "disabled" | "invalid";
 /**
  * Theme overrides for the Select component
  */
@@ -180,8 +180,12 @@ export interface SelectThemeOverrides {
     optionStyle?: string;
     /** Style for selected options */
     selectedOptionStyle?: string;
+    /** Style for highlighted options (keyboard navigation) */
+    highlightedOptionStyle?: string;
     /** Style for disabled options */
     disabledOptionStyle?: string;
+    /** Style for create option */
+    createOptionStyle?: string;
     /** Style for the helper text */
     helperTextStyle?: string;
     /** State styles for the helper text */

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

@@ -1,4 +1,7 @@
-import { SelectButton, SelectOptions, SelectOption, Select } from './Select';
-export { SelectButton, SelectOptions, SelectOption, Select };
-export type { SelectProps, SelectOption as SelectOptionType, SelectSize, SelectState, SelectThemeOverrides } from './Select.types';
-export { selectTheme } from './Select.theme';
+export { Select, SelectButton, SelectOptions, SelectOption, } from "./Select";
+export { SelectProvider, SelectContext, useSelectContext, } from "./Select";
+export { useSelectState, } from "./Select";
+export { selectTheme } from "./Select.theme";
+export type { SelectProps, SelectOption as SelectOptionType, SelectSize, SelectState, SelectThemeOverrides, SelectButtonProps, SelectOptionsProps, SelectOptionProps, } from "./Select.types";
+export type { UseSelectStateProps, UseSelectStateReturn, } from "./useSelectState";
+export type { SelectContextValue, SelectProviderProps, SelectOptionsExtendedProps, } from "./Select";