@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

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

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import React__default, { createContext, useMemo, useRef, useCallback, useEffect, useContext } from 'react';
 import { AnimatePresence, motion } from 'motion/react';
@@ -7,47 +8,16 @@ import { FormLabel } from '../FormLabel/FormLabel.js';
 import { Input } from '../Input/Input.js';
 import '../Input/Input.theme.js';
 import { createDropdownAnimations } from './Select.animations.js';
-import { ChevronUpDownIcon } from '../../../icons/core/ChevronUpDown.js';
+import { ChevronUpDownIcon, PlusIcon, MagnifyingGlassIcon, CheckIcon } from '@heroicons/react/24/outline';
 import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { cn } from '../../../utils/cn.js';
 import { isValidTypeaheadChar, findNextMatchingOption, TYPEAHEAD_TIMEOUT_MS } from '../../../utils/typeaheadUtils.js';
-import { PlusIcon, CheckIcon, MagnifyingGlassIcon } from '@heroicons/react/24/outline';
 import { Tag } from '../../core/Tag/Tag.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 import { useSelectState } from './useSelectState.js';
 
-// ============================================================================
-// Dark Mode Hook
-// ============================================================================
-/**
- * Hook to detect dark mode state from document
- */
-const useDarkMode = () => {
-    const [isDark, setIsDark] = React__default.useState(false);
-    useEffect(() => {
-        if (typeof document === "undefined")
-            return;
-        const checkDarkMode = () => {
-            const hasDarkClass = document.documentElement.classList.contains("dark") ||
-                document.body.classList.contains("dark") ||
-                document.querySelector(".dark") !== null;
-            setIsDark(hasDarkClass);
-        };
-        checkDarkMode();
-        // Observe class changes on html and body
-        const observer = new MutationObserver(checkDarkMode);
-        observer.observe(document.documentElement, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        observer.observe(document.body, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        return () => observer.disconnect();
-    }, []);
-    return isDark;
-};
 /**
  * SelectContext - exported for external consumption
  */
@@ -105,7 +75,7 @@ function SelectProvider({ children, selectState, size = "md", componentState = "
 /**
  * Select Button Component
  */
-const SelectButton = ({ id, disabled, isOpen, state = "default", size = "md", iconStart, iconEnd, className = "", onClick, onFocus, onBlur, children, }) => {
+const SelectButton = ({ id, disabled, isOpen, state = "default", size = "md", iconStart, iconEnd, contentStart, contentEnd, className = "", onClick, onFocus, onBlur, onKeyDown, children, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedby, "aria-labelledby": ariaLabelledby, }) => {
     var _a, _b, _c, _d, _e, _f;
     const { theme, buttonRef } = useSelectContext();
     const baseStyle = theme.baseStyle || "";
@@ -119,18 +89,27 @@ const SelectButton = ({ id, disabled, isOpen, state = "default", size = "md", ic
     const iconEndStyle = theme.iconEndStyle || "";
     const iconStartPadding = iconStart ? ((_e = theme.iconPadding) === null || _e === void 0 ? void 0 : _e.left) || "" : "";
     const iconEndPadding = iconEnd ? ((_f = theme.iconPadding) === null || _f === void 0 ? void 0 : _f.right) || "" : "";
+    // Size-aware content slot style (mirrors Input.theme contentStyle)
+    const contentSlotStyle = `flex items-center px-3 ${size === "sm"
+        ? "text-sm"
+        : size === "lg"
+            ? "text-base"
+            : "text-sm"} text-[var(--color-text-muted)] shrink-0 dark:text-[var(--color-neutral-500)]`;
     // Use either the themed focus state or directly apply the focus classes if the theme is not working
     const activeFocusState = isOpen
         ? focusStateStyle ||
-            "outline-2 outline-[var(--color-primary)] -outline-offset-1 ring-4 ring-[var(--color-primary)]/10"
+            "shadow-[inset_0_0_0_1px_var(--color-primary)] ring-4 ring-[var(--color-primary)]/10"
         : "";
-    return (jsx("div", { className: cn(buttonWrapperStyle), children: jsxs("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", children: [iconStart && jsx("span", { className: iconStartStyle, children: iconStart }), children, iconEnd && jsx("span", { className: iconEndStyle, children: iconEnd })] }) }));
+    return (jsxs("div", { className: cn(buttonWrapperStyle, "flex items-stretch"), children: [contentStart && (jsx("div", { "data-slot": "content-start", className: cn(contentSlotStyle, "pr-0 border-r border-[var(--color-border)]"), children: contentStart })), jsxs("button", { ref: buttonRef, id: id, type: "button", className: cn(baseStyle, sizeStyle, stateStyle, hoverStateStyle, activeFocusState, iconStartPadding, iconEndPadding, buttonStyle, "flex-1 min-w-0", className), onClick: onClick, onFocus: onFocus, onBlur: onBlur, onKeyDown: onKeyDown, disabled: disabled, "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": isOpen && id ? `${id}-listbox` : undefined, "aria-labelledby": ariaLabelledby, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedby, children: [iconStart && jsx("span", { className: iconStartStyle, children: iconStart }), children, iconEnd && jsx("span", { className: iconEndStyle, children: iconEnd })] }), contentEnd && (jsx("div", { "data-slot": "content-end", className: cn(contentSlotStyle, "pl-0 border-l border-[var(--color-border)]"), children: contentEnd }))] }));
 };
 /**
  * Select Options Component
  */
-const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, children, portal = true, placement = "bottom-start", offset = 4, triggerRef: customTriggerRef, }) => {
+const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, children, portal = true, placement = "bottom-start", offset = 4, triggerRef: customTriggerRef, listboxId, "aria-labelledby": ariaLabelledby, elevation, lift, }) => {
     var _a;
+    // Relative elevation: the listbox lifts above its host surface (overlay base = 5)
+    // so a Select inside a Popover/Modal still reads as a higher plane.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     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
@@ -151,7 +130,7 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
     // Create direction-aware animations based on actual placement
     const animations = createDropdownAnimations(isFlipped);
     const optionsContainerStyle = theme.optionsContainerStyle || "";
-    const searchInputStyle = theme.searchInputStyle || "";
+    theme.searchInputStyle || "";
     // Convert maxHeight to a valid CSS value
     const maxHeightValue = typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight;
     // Combine refs for portal and legacy usage
@@ -286,22 +265,12 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
             searchInputRef.current.select();
         }
     }, [isOpen, searchable]);
-    // Add effect to measure content after render for improved positioning
-    useEffect(() => {
-        if (isOpen && contentRef.current) {
-            // Trigger recalculation after content renders
-            const timer = setTimeout(() => {
-                // Hook will remeasure automatically due to contentRef dependency
-            }, 0);
-            return () => clearTimeout(timer);
-        }
-    }, [isOpen, children, filteredOptions.length]);
     // Handle search input change
     const handleSearchChange = (e) => {
         setSearchValue(e.target.value);
         setHighlightedIndex(-1); // Reset highlighted index when search changes
     };
-    const optionsContent = (jsx(AnimatePresence, { mode: "wait", children: isOpen && (jsxs(motion.div, { ref: combinedRef, className: cn(optionsContainerStyle, className), style: {
+    const optionsContent = (jsx(AnimatePresence, { mode: "wait", children: isOpen && (jsx(motion.div, { ref: combinedRef, id: listboxId, className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: true }), optionsContainerStyle, className), style: {
                 ...cssVariables,
                 overscrollBehavior: "contain",
                 ...(portal
@@ -314,16 +283,16 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
                     : {
                         maxHeight: searchable ? "none" : maxHeightValue,
                     }),
-            }, role: "listbox", tabIndex: -1, variants: animations, initial: "initial", animate: "visible", exit: "exit", children: [searchable && (jsx("div", { className: `sticky top-0 py-1 bg-[var(--color-background)] z-[10000] border-b border-[var(--color-border)] ${searchInputStyle}`, style: {
-                        "--form-radius": "0",
-                    }, children: jsx(Input, { placeholder: "Search...", value: searchValue, onChange: handleSearchChange, type: "search", ref: searchInputRef, className: "w-full block bg-[var(--color-background)] 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: jsx(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: {
-                            border: "none",
-                            outline: "none",
-                            boxShadow: "none",
-                        } }) })), children] })) }));
+            }, role: "listbox", "aria-labelledby": ariaLabelledby, tabIndex: -1, variants: animations, initial: "initial", animate: "visible", exit: "exit", children: jsxs(SurfaceProvider, { level: surfaceLevel, children: [searchable && (jsx(Input, { placeholder: "Search...", "aria-label": "Search options", value: searchValue, onChange: handleSearchChange, type: "search", ref: searchInputRef, iconStart: jsx(MagnifyingGlassIcon, { strokeWidth: 2, className: cn("size-4 text-[var(--color-text-secodary)] transition-opacity", 
+                            // Focus can't drive this — the search autofocuses on open, so it's
+                            // always focused while visible. Emphasize on "actively searching" instead.
+                            searchValue ? "opacity-100" : "opacity-70") }), 
+                        // The field fill, inset border-shadow, and focus ring all live on the
+                        // inputGroup — strip them so the search blends into the dropdown surface.
+                        inputGroupClassName: "!bg-transparent !shadow-none !ring-0 flex items-center" })), children] }) })) }));
     // Use portal if enabled and client-side - wrap with dark class for dark mode support
     if (portal && isClient) {
-        return createPortal(jsx("div", { className: isDarkMode ? "dark" : undefined, children: optionsContent }), document.body);
+        return createPortal(jsx("div", { "data-flikkui-portal": "", className: isDarkMode ? "dark" : undefined, children: optionsContent }), document.body);
     }
     return optionsContent;
 };
@@ -335,7 +304,7 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
  */
 const SelectOption = ({ value, isSelected, disabled, className = "", onSelect, children, }) => {
     var _a;
-    const { highlightedIndex, setHighlightedIndex, filteredOptions, theme, selectOption, } = useSelectContext();
+    const { highlightedIndex, setHighlightedIndex, filteredOptions, searchValue, theme, selectOption, } = useSelectContext();
     const optionStyle = theme.optionStyle || "";
     const selectedOptionStyle = theme.selectedOptionStyle || "";
     const disabledOptionStyle = theme.disabledOptionStyle || "";
@@ -343,7 +312,15 @@ const SelectOption = ({ value, isSelected, disabled, className = "", onSelect, c
     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;
+    // Compound children (e.g. custom avatar options) are authored from the full
+    // options list, so they bypass the data-driven `filteredOptions.map` filtering.
+    // When a search is active, hide any child the filter excluded so the compound
+    // API matches the data-driven path instead of rendering non-matches.
+    if (searchValue && optionIndex === -1)
+        return null;
+    // Guard against the `-1 === -1` false positive: an unmatched option (index -1)
+    // must never read as "highlighted" just because nothing is highlighted yet.
+    const isHighlighted = optionIndex >= 0 && optionIndex === highlightedIndex;
     // Check if this is the create option
     const isCreateOption = ((_a = filteredOptions[optionIndex]) === null || _a === void 0 ? void 0 : _a.id) === "__create__";
     const handleClick = () => {
@@ -358,7 +335,9 @@ const SelectOption = ({ value, isSelected, disabled, className = "", onSelect, c
     const keyboardHighlightStyle = isHighlighted ? highlightedOptionStyle : "";
     // Style create option differently
     const createOptionStyle = isCreateOption ? createOptionStyleTheme : "";
-    return (jsx("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: children }));
+    return (jsxs("div", { className: cn(optionStyle, isSelected && selectedOptionStyle, 
+        // Reserve room on the right so a long, truncated label never runs under the check.
+        isSelected && !isCreateOption && "pr-9", disabled && disabledOptionStyle, keyboardHighlightStyle, createOptionStyle, className), role: "option", "aria-selected": isSelected, "aria-disabled": disabled, "data-option-index": optionIndex, onMouseEnter: () => !disabled && setHighlightedIndex(optionIndex), onClick: handleClick, children: [children, isSelected && !isCreateOption && (jsx("span", { className: theme.checkIconStyle, children: jsx(CheckIcon, { className: "size-4", strokeWidth: 2 }) }))] }));
 };
 // ============================================================================
 // Main Select Component
@@ -387,7 +366,7 @@ const SelectOption = ({ value, isSelected, disabled, className = "", onSelect, c
  * />
  * ```
  */
-const SelectInner = ({ 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, multiple = false, maxDisplayedChips = 3, children, }, ref) => {
+const SelectInner = ({ id, name, size = "md", state = "default", value, displayValue, placeholder = "Select an option", disabled = false, required = false, options = [], label, helperText, onChange, onFocus, onBlur, iconStart, iconEnd, contentStart, contentEnd, theme: themeOverrides, className = "", wrapperClassName = "", searchable = false, searchPlaceholder = "Search options...", portal = true, placement = "bottom-start", offset = 8, enableTypeahead = true, creatable = false, onCreateOption, createLabel, multiple = false, maxDisplayedChips = 3, elevation, lift, children, }, ref) => {
     var _a;
     // Merge theme with overrides
     const theme = useMemo(() => ({ ...selectTheme, ...(themeOverrides || {}) }), [themeOverrides]);
@@ -403,7 +382,7 @@ const SelectInner = ({ id, name, size = "md", state = "default", value, displayV
         enableTypeahead,
         multiple,
     });
-    const { isOpen, setIsOpen, selectedValue, filteredOptions, selectedOption, selectedValues, isValueSelected, removeValue, } = selectState;
+    const { isOpen, setIsOpen, selectedValue, filteredOptions, selectedOption, selectedValues, isValueSelected, removeValue, setHighlightedIndex, } = selectState;
     // Cast triggerRef to buttonRef type
     selectState.triggerRef;
     // Build display for multi-select chips
@@ -415,7 +394,7 @@ const SelectInner = ({ id, name, size = "md", state = "default", value, displayV
             .filter(Boolean);
         const displayed = selectedOpts.slice(0, maxDisplayedChips);
         const overflow = selectedOpts.length - maxDisplayedChips;
-        return (jsxs("div", { className: theme.chipContainerStyle, children: [jsx(AnimatePresence, { mode: "popLayout", children: displayed.map((opt) => (jsx(Tag, { size: "sm", onRemove: () => removeValue(opt.value), className: "shrink-0 max-w-[120px] truncate rounded-md border-none", children: opt.label }, String(opt.id)))) }), overflow > 0 && (jsxs("span", { className: theme.chipOverflowStyle, children: ["+", overflow, " more"] }))] }));
+        return (jsxs("div", { className: theme.chipContainerStyle, children: [jsx(AnimatePresence, { mode: "popLayout", children: displayed.map((opt) => (jsx(Tag, { size: "sm", onRemove: () => removeValue(opt.value), className: "shrink-0 max-w-[120px] truncate", children: opt.label }, String(opt.id)))) }), overflow > 0 && (jsxs("span", { className: theme.chipOverflowStyle, children: ["+", overflow, " more"] }))] }));
     }, [multiple, selectedValues, options, maxDisplayedChips, theme.chipContainerStyle, theme.chipOverflowStyle, removeValue]);
     const computedDisplayValue = displayValue ||
         (multiple
@@ -429,30 +408,55 @@ const SelectInner = ({ id, name, size = "md", state = "default", value, displayV
             setIsOpen((prev) => !prev);
         }
     };
+    // WAI-ARIA APG listbox-button pattern: ArrowDown/ArrowUp on the closed
+    // trigger opens the listbox, moving the initial highlight to the first
+    // option (ArrowDown) or last option (ArrowUp).
+    const handleButtonKeyDown = (event) => {
+        if (disabled || isOpen)
+            return;
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            setIsOpen(true);
+            setHighlightedIndex(event.key === "ArrowDown" ? 0 : filteredOptions.length - 1);
+        }
+    };
     // Helper text state style
     const helperTextStateStyle = ((_a = theme.helperTextStates) === null || _a === void 0 ? void 0 : _a[state]) || "";
     const helperTextStyle = theme.helperTextStyle || "";
     // Container style
     const containerStyle = theme.containerStyle || "";
     // Default chevron icon if no iconEnd provided
-    const defaultChevronIcon = jsx(ChevronUpDownIcon, { size: 16, className: "" });
+    const defaultChevronIcon = jsx(ChevronUpDownIcon, { className: "size-4" });
     // Generate a unique ID if not provided
     const generatedId = React__default.useId();
     const selectId = id || generatedId;
-    return (jsx(SelectProvider, { selectState: selectState, size: size, componentState: state, theme: themeOverrides, searchable: searchable, enableTypeahead: enableTypeahead, children: jsxs("div", { ref: ref, className: cn("relative", containerStyle, wrapperClassName), children: [label && (jsx(FormLabel, { htmlFor: selectId, required: required, children: label })), jsx(SelectButton, { id: selectId, disabled: disabled, isOpen: isOpen, state: state, size: size, iconStart: iconStart, iconEnd: iconEnd || defaultChevronIcon, onClick: handleButtonClick, onFocus: onFocus, onBlur: onBlur, className: className, children: jsx("span", { className: cn(multiple && selectedValues.length > 0
+    // The listbox needs the same accessible name as the trigger — thread the
+    // FormLabel id through to both so screen readers announce what the
+    // listbox (role="listbox") is for, not just the trigger button.
+    const labelId = label && typeof label === 'string' ? `${selectId}-label` : undefined;
+    return (jsx(SelectProvider, { selectState: selectState, size: size, componentState: state, theme: themeOverrides, searchable: searchable, enableTypeahead: enableTypeahead, children: jsxs("div", { ref: ref, className: cn("relative", containerStyle, wrapperClassName), children: [label && (typeof label === 'string' ? (jsx(FormLabel, { id: `${selectId}-label`, htmlFor: selectId, required: required, state: state, children: label })) : (label)), jsx(SelectButton, { id: selectId, disabled: disabled, isOpen: isOpen, state: state, size: size, iconStart: iconStart, iconEnd: iconEnd || defaultChevronIcon, contentStart: contentStart, contentEnd: contentEnd, onClick: handleButtonClick, onFocus: onFocus, onBlur: onBlur, onKeyDown: handleButtonKeyDown, className: className, "aria-labelledby": labelId, "aria-invalid": state === "invalid" || undefined, "aria-describedby": helperText ? `${selectId}-helper` : undefined, children: jsx("span", { className: cn(multiple && selectedValues.length > 0
                             ? "flex min-w-0"
                             : "block truncate", (multiple ? selectedValues.length > 0 : selectedOption)
                             ? theme.valueTextStyle
-                            : theme.placeholderTextStyle), children: computedDisplayValue }) }), jsx(SelectOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), portal: portal, placement: placement, offset: offset, children: children ||
-                        filteredOptions.map((option) => {
-                            const isCreateOption = option.id === "__create__";
-                            const isSelected = multiple
-                                ? isValueSelected(option.value)
-                                : option.value === selectedValue;
-                            return (jsx(SelectOption, { value: option.value, isSelected: isSelected, disabled: option.disabled || false, children: isCreateOption ? (jsxs("span", { className: "flex items-center gap-2", children: [jsx(PlusIcon, { className: "size-4 shrink-0" }), jsx("span", { className: "block truncate", children: option.label })] })) : multiple ? (jsxs(Fragment, { children: [jsx("span", { className: "block truncate", children: option.label }), isSelected && (jsx("span", { className: theme.checkIconStyle, children: jsx(CheckIcon, { className: "size-4", strokeWidth: 2 }) }))] })) : (jsx("span", { className: "block truncate", children: option.label })) }, option.id));
-                        }) }), helperText && (jsx("p", { className: cn(helperTextStyle, helperTextStateStyle), children: helperText })), name && (jsx("input", { type: "hidden", name: name, value: selectedValue !== undefined ? String(selectedValue) : "" }))] }) }));
+                            : theme.placeholderTextStyle), children: computedDisplayValue }) }), jsx(SelectOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), portal: portal, placement: placement, offset: offset, listboxId: `${selectId}-listbox`, "aria-labelledby": labelId, elevation: elevation, lift: lift, children: children ||
+                        (() => {
+                            const displayedOptions = filteredOptions.length > 100
+                                ? filteredOptions.slice(0, 100)
+                                : filteredOptions;
+                            return (jsxs(Fragment, { children: [displayedOptions.map((option) => {
+                                        const isCreateOption = option.id === "__create__";
+                                        const isSelected = multiple
+                                            ? isValueSelected(option.value)
+                                            : option.value === selectedValue;
+                                        return (jsx(SelectOption, { value: option.value, isSelected: isSelected, disabled: option.disabled || false, children: isCreateOption ? (jsxs("span", { className: "flex items-center gap-2", children: [jsx(PlusIcon, { className: "size-4 shrink-0" }), jsx("span", { className: "block truncate", children: option.label })] })) : (
+                                            // The selected check is rendered by SelectOption itself (single +
+                                            // multiple), so the call site only supplies the label.
+                                            jsx("span", { className: "block truncate", children: option.label })) }, option.id));
+                                    }), filteredOptions.length > 100 && (jsxs("div", { className: "px-3 py-2 text-xs text-[var(--color-text-muted)] text-center border-t border-[var(--color-border)]", children: ["Showing 100 of ", filteredOptions.length, " results \u2014 refine your search"] }))] }));
+                        })() }), helperText && (typeof helperText === 'string' ? (jsx("p", { id: `${selectId}-helper`, className: cn(helperTextStyle, helperTextStateStyle), children: helperText })) : (helperText)), name && (jsx("input", { type: "hidden", name: name, value: selectedValue !== undefined ? String(selectedValue) : "" }))] }) }));
 };
-const Select = React__default.forwardRef(SelectInner);
-Select.displayName = "Select";
+const SelectForwarded = React__default.forwardRef(SelectInner);
+SelectForwarded.displayName = "Select";
+const Select = SelectForwarded;
 
 export { Select, SelectButton, SelectContext, SelectOption, SelectOptions, SelectProvider, useSelectContext, useSelectState };

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

@@ -11,12 +11,12 @@ const selectTheme = {
     baseStyle: formsBaseTheme.inputGroupBaseStyle + " items-center justify-between",
     // Button wrapper style
     buttonWrapperStyle: "relative w-full",
-    // 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)]",
+    // Button style — field fill lifts one rung above the host surface (via --field-fill)
+    buttonStyle: "w-full cursor-pointer bg-[var(--field-fill)]",
     // Placeholder text style - matches Input placeholder styling
     placeholderTextStyle: formsBaseTheme.placeholderStyle,
     // Selected value text style
-    valueTextStyle: "text-[var(--color-text-primary)] dark:text-[var(--color-neutral-200)]",
+    valueTextStyle: "text-[var(--color-text-primary)]",
     // Size variants - composed from atomic tokens
     sizes: {
         sm: `${formsBaseTheme.sizes.sm.text} ${formsBaseTheme.sizes.sm.padding} ${formsBaseTheme.sizes.sm.height}`,

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

@@ -1,10 +1,11 @@
 import React from "react";
 import type { SelectPlacement } from "../../../hooks/useSelectPortal";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 /**
  * Select value option type
  * @template T The type of the option value
  */
-export interface SelectOption<T = any> {
+export interface SelectOption<T = unknown> {
     /** Unique identifier for the option */
     id: string | number;
     /** Display label for the option */
@@ -25,7 +26,7 @@ export interface SelectBaseProps {
  * Select component props
  * @template T The type of the select value
  */
-export interface SelectProps<T = any> extends SelectBaseProps {
+export interface SelectProps<T = unknown> extends SelectBaseProps {
     /** ID for the select component */
     id?: string;
     /** Name for the select component */
@@ -46,10 +47,10 @@ export interface SelectProps<T = any> extends SelectBaseProps {
     required?: boolean;
     /** Array of options to display */
     options: SelectOption<T>[];
-    /** Label text for the select */
-    label?: string;
-    /** Helper text displayed below the select */
-    helperText?: string;
+    /** Label for the select — pass a string for default styling, or a ReactNode for full control */
+    label?: React.ReactNode;
+    /** Helper text below the select — pass a string for default styling, or a ReactNode for full control */
+    helperText?: React.ReactNode;
     /** Enable multi-select mode — value becomes T[] and chips are rendered in trigger */
     multiple?: boolean;
     /** Maximum number of chips to display before showing "+N more" (default: 3) */
@@ -64,6 +65,10 @@ export interface SelectProps<T = any> extends SelectBaseProps {
     iconStart?: React.ReactNode;
     /** Right icon to display in the select button (default is chevron) */
     iconEnd?: React.ReactNode;
+    /** Structural content rendered before iconStart (e.g. a prefix label or nested Select) */
+    contentStart?: React.ReactNode;
+    /** Structural content rendered after iconEnd (e.g. a suffix label or nested Select) */
+    contentEnd?: React.ReactNode;
     /** Children to render instead of default options */
     children?: React.ReactNode;
     /** Component-level theme overrides */
@@ -72,7 +77,17 @@ export interface SelectProps<T = any> extends SelectBaseProps {
     searchable?: boolean;
     /** Placeholder text for the search input */
     searchPlaceholder?: string;
-    /** Whether to use portal rendering for dropdown (default: true) */
+    /**
+     * Whether to render the dropdown in a portal to `document.body` (default: true).
+     * Keep the default when placing a Select inside a Popover, Modal, Drawer, or any
+     * container with `overflow`/`transform`: portaling floats the dropdown ABOVE the
+     * container instead of being clipped by it, and the `data-flikkui-portal` convention
+     * keeps the ancestor overlay open when an option is picked. Setting `portal` to `false`
+     * renders the dropdown inline, where an overflow/transform ancestor (e.g. Popover.Body)
+     * clips it — only use that when the Select lives in a non-clipping, statically-positioned
+     * container and you specifically need the dropdown inside the normal flow.
+     * @default true
+     */
     portal?: boolean;
     /** Placement of the dropdown relative to trigger */
     placement?: SelectPlacement;
@@ -88,6 +103,13 @@ export interface SelectProps<T = any> extends SelectBaseProps {
     onCreateOption?: (inputValue: string) => void;
     /** Custom label for the create option (default: "Create '{inputValue}'") */
     createLabel?: string | ((inputValue: string) => string);
+    /**
+     * Pin the listbox surface elevation rung (overrides the automatic relative lift).
+     * A rung number (1–8) or a semantic alias ("surface"/"raised"/"overlay"…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the listbox's base rung. */
+    lift?: boolean;
 }
 /**
  * Select button props
@@ -113,8 +135,20 @@ export interface SelectButtonProps extends SelectBaseProps {
     onFocus?: (event: React.FocusEvent<HTMLButtonElement>) => void;
     /** Called when the button loses focus */
     onBlur?: (event: React.FocusEvent<HTMLButtonElement>) => void;
+    /** Called on keydown (used to open the listbox on ArrowDown/ArrowUp while closed) */
+    onKeyDown?: (event: React.KeyboardEvent<HTMLButtonElement>) => void;
     /** Children to render inside the button */
     children?: React.ReactNode;
+    /** Marks the button as invalid for assistive technologies */
+    "aria-invalid"?: boolean;
+    /** ID of the element that describes this button (e.g. helper text) */
+    "aria-describedby"?: string;
+    /** ID of the element that labels this button (e.g. form label) */
+    "aria-labelledby"?: string;
+    /** Structural content rendered before iconStart */
+    contentStart?: React.ReactNode;
+    /** Structural content rendered after iconEnd */
+    contentEnd?: React.ReactNode;
 }
 /**
  * Select options container props
@@ -134,11 +168,18 @@ export interface SelectOptionsProps extends SelectBaseProps {
     placement?: SelectPlacement;
     /** Offset between trigger and dropdown in pixels */
     offset?: number;
+    /**
+     * Pin the listbox surface elevation rung (overrides the automatic relative lift).
+     * A rung number (1–8) or a semantic alias ("surface"/"raised"/"overlay"…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the listbox's base rung. */
+    lift?: boolean;
 }
 /**
  * Select option props
  */
-export interface SelectOptionProps<T = any> extends SelectBaseProps {
+export interface SelectOptionProps<T = unknown> extends SelectBaseProps {
     /** Option value */
     value: T;
     /** Whether the option is currently selected */

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

@@ -1,3 +1,4 @@
+"use client";
 import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
 
 /**
@@ -96,6 +97,7 @@ function useSelectState({ options = [], value, onChange, searchable = false, cre
     }, [selectedValues, onChange]);
     // Select an option
     const selectOption = useCallback((newValue, isCreateAction = false) => {
+        var _a;
         // Handle create action callback
         if (isCreateAction && onCreateOption) {
             onCreateOption(String(newValue));
@@ -120,6 +122,11 @@ function useSelectState({ options = [], value, onChange, searchable = false, cre
         // Close and reset
         setIsOpen(false);
         setSearchValue("");
+        // Restore focus to the trigger. The keyboard (Enter-to-select) path
+        // never blurs the trigger in the first place, so this is a no-op there;
+        // mouse-click selection targets a non-focusable option div and can leave
+        // focus stranded, so explicitly return it here to match.
+        (_a = triggerRef.current) === null || _a === void 0 ? void 0 : _a.focus();
     }, [selectedValue, selectedValues, onChange, onCreateOption, multiple]);
     // Reset state when closing
     useEffect(() => {

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

@@ -1,5 +1,5 @@
 import React from "react";
 import type { SelectableCardProps } from "./SelectableCard.types";
-export declare const SelectableCard: React.ForwardRefExoticComponent<Omit<SelectableCardProps, "ref"> & React.RefAttributes<HTMLDivElement>> & {
+export declare const SelectableCard: React.ForwardRefExoticComponent<SelectableCardProps & React.RefAttributes<HTMLDivElement>> & {
     Group: React.ForwardRefExoticComponent<import("./SelectableCard.types").SelectableCardGroupProps & React.RefAttributes<HTMLDivElement>>;
 };

package/dist/components/forms/SelectableCard/SelectableCard.js

@@ -1,53 +1,69 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useId } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
-import { CheckIcon } from '@heroicons/react/24/outline';
 import { cn } from '../../../utils/cn.js';
-import { useSelectableCardContext } from './SelectableCardContext.js';
+import { Radio } from '../Radio/Radio.js';
+import { Checkbox } from '../Checkbox/Checkbox.js';
+import { useOptionalSelectableCardContext } from './SelectableCardContext.js';
+import { selectableCardTheme } from './SelectableCard.theme.js';
 import { SelectableCardGroup } from './SelectableCardGroup.js';
 import { cardVariants } from './SelectableCard.animations.js';
 
-// ─── Radio Indicator ─────────────────────────────────────────────────────────
-const RadioIndicator = ({ checked }) => (jsxs("div", { className: "relative flex-shrink-0 flex items-center justify-center size-5", children: [jsx("div", { className: cn("size-5 rounded-full border-2 transition-colors duration-200", checked
-                ? "border-[var(--color-primary)]"
-                : "border-[var(--color-border)]") }), jsx("div", { className: cn("absolute inset-0 m-auto rounded-full bg-[var(--color-primary)] transition-all duration-200", checked ? "size-2.5 opacity-100" : "size-0 opacity-0") })] }));
-// ─── Checkbox Indicator ──────────────────────────────────────────────────────
-const CheckboxIndicator = ({ checked }) => (jsx("div", { className: cn("flex-shrink-0 flex items-center justify-center size-5 rounded-[4px] border-2 transition-colors duration-200", checked
-        ? "border-[var(--color-primary)] bg-[var(--color-primary)]"
-        : "border-[var(--color-border)] bg-[var(--color-background)]"), children: checked && jsx(CheckIcon, { className: "size-3.5 stroke-white", strokeWidth: 3 }) }));
 // ─── SelectableCard ──────────────────────────────────────────────────────────
-const SelectableCardRoot = React__default.forwardRef(({ value, disabled: cardDisabled, className, children, ...props }, ref) => {
-    const content = children;
-    const ctx = useSelectableCardContext();
+const SelectableCardRoot = React__default.forwardRef(({ value, disabled: cardDisabled, checked: standaloneChecked, onChange: standaloneOnChange, indicator: standaloneIndicator, indicatorPosition: cardIndicatorPosition, size: cardSize, className, children, onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...props }, ref) => {
+    var _a;
+    const ctx = useOptionalSelectableCardContext();
+    const isStandalone = ctx === undefined;
     const inputId = useId();
     const shouldReduceMotion = useReducedMotion();
-    const isDisabled = cardDisabled || ctx.disabled;
-    const isSelected = ctx.type === "single"
-        ? ctx.value === value
-        : Array.isArray(ctx.value) && ctx.value.includes(value);
+    const theme = isStandalone ? selectableCardTheme : ctx.theme;
+    const isDisabled = cardDisabled || (!isStandalone && ctx.disabled);
+    const isSelected = isStandalone
+        ? (standaloneChecked !== null && standaloneChecked !== void 0 ? standaloneChecked : false)
+        : ctx.type === "single"
+            ? ctx.value === value
+            : Array.isArray(ctx.value) && ctx.value.includes(value);
+    const resolvedIndicator = isStandalone
+        ? (standaloneIndicator !== null && standaloneIndicator !== void 0 ? standaloneIndicator : "radio")
+        : ctx.indicator;
+    const resolvedIndicatorPosition = cardIndicatorPosition !== null && cardIndicatorPosition !== void 0 ? cardIndicatorPosition : (isStandalone ? "end" : ctx.indicatorPosition);
+    const resolvedSize = cardSize !== null && cardSize !== void 0 ? cardSize : (isStandalone ? "md" : ctx.size);
+    const indicatorSize = "sm";
     const handleClick = () => {
         if (isDisabled)
             return;
-        ctx.onChange(value);
+        if (isStandalone) {
+            standaloneOnChange === null || standaloneOnChange === void 0 ? void 0 : standaloneOnChange(!isSelected, value);
+        }
+        else {
+            ctx.onChange(value);
+        }
     };
     const handleKeyDown = (e) => {
         if (isDisabled)
             return;
         if (e.key === " " || e.key === "Enter") {
             e.preventDefault();
-            ctx.onChange(value);
+            handleClick();
         }
     };
-    const inputType = ctx.type === "single" ? "radio" : "checkbox";
+    const inputType = isStandalone
+        ? "checkbox"
+        : ctx.type === "single"
+            ? "radio"
+            : "checkbox";
+    const role = isStandalone
+        ? "checkbox"
+        : ctx.type === "single"
+            ? "radio"
+            : "checkbox";
     const animated = !shouldReduceMotion && !isDisabled;
     const motionProps = animated
-        ? {
-            variants: cardVariants,
-            initial: "idle",
-            whileTap: "tap",
-        }
+        ? { variants: cardVariants, initial: "idle", whileTap: "tap" }
         : {};
-    return (jsxs(motion.div, { ref: ref, role: ctx.type === "single" ? "radio" : "checkbox", "aria-checked": isSelected, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : 0, "data-selected": isSelected, "data-disabled": isDisabled || undefined, className: cn(ctx.theme.card, isSelected && ctx.theme.selectedCard, isDisabled && ctx.theme.disabledCard, className), onClick: handleClick, onKeyDown: handleKeyDown, ...motionProps, ...props, children: [jsx("input", { type: inputType, id: inputId, name: ctx.name, value: value, checked: isSelected, disabled: isDisabled, onChange: () => { }, className: "sr-only", tabIndex: -1, "aria-hidden": true }), jsx("div", { className: ctx.theme.contentWrapper, children: content }), ctx.indicator !== "none" && (jsx("div", { className: ctx.theme.indicator, children: ctx.indicator === "radio" ? (jsx(RadioIndicator, { checked: isSelected })) : (jsx(CheckboxIndicator, { checked: isSelected })) }))] }));
+    const indicatorNode = resolvedIndicator !== "none" && (jsx("div", { className: cn(theme.indicator, "pointer-events-none"), "aria-hidden": "true", children: resolvedIndicator === "radio" ? (jsx(Radio, { value: value, checked: isSelected, onChange: () => { }, state: isDisabled ? "disabled" : "default", size: indicatorSize })) : (jsx(Checkbox, { value: value, checked: isSelected, onChange: () => { }, state: isDisabled ? "disabled" : "default", size: indicatorSize })) }));
+    return (jsxs(motion.div, { ref: ref, role: role, "aria-checked": isSelected, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : 0, "data-selected": isSelected, "data-disabled": isDisabled || undefined, className: cn(theme.card, (_a = theme.cardSizes) === null || _a === void 0 ? void 0 : _a[resolvedSize], isSelected && theme.selectedCard, isDisabled && theme.disabledCard, className), onClick: handleClick, onKeyDown: handleKeyDown, ...motionProps, ...props, children: [jsx("input", { type: inputType, id: inputId, name: isStandalone ? undefined : ctx === null || ctx === void 0 ? void 0 : ctx.name, value: value, checked: isSelected, disabled: isDisabled, onChange: () => { }, className: "sr-only", tabIndex: -1, "aria-hidden": true }), resolvedIndicatorPosition === "start" && indicatorNode, jsx("div", { className: theme.contentWrapper, children: children }), resolvedIndicatorPosition === "end" && indicatorNode] }));
 });
 SelectableCardRoot.displayName = "SelectableCard";
 // ─── Compound Export ─────────────────────────────────────────────────────────