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

package/dist/components/forms/ColorPicker/ColorPicker.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useRef, useMemo, useState, useCallback, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -27,17 +28,28 @@ const DEFAULT_GRADIENT = {
         { id: 'stop-2', color: '#FFFFFF', position: 100 },
     ],
 };
+/**
+ * In gradient/image mode the controlled `value` is a CSS gradient string, not a solid
+ * color — don't feed it to `parseColor` (it would emit an "Unsupported color format" warning
+ * and return null). Skip parsing for gradient values.
+ */
+const isGradientString = (v) => /^(?:repeating-)?(?:linear|radial|conic)-gradient\(/.test(v.trim());
 /**
  * ColorPicker Root Component
  * Follows Flikkui compound component pattern (similar to Accordion, Tabs, Popover)
  */
-const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000000', onChange, format: initialFormat = 'hex', showAlpha = true, showEyeDropper = true, presetColors, savedColors: savedColorsProp, onSavedColorsChange, defaultMode = 'solid', mode: modeProp, onModeChange, gradientValue: gradientProp, onGradientChange, size = 'md', state = 'default', disabled = false, label, helperText, required = false, theme, className, id, children, ...props }, ref) => {
+const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000000', onChange, format: initialFormat = 'hex', showAlpha = true, showEyeDropper = true, presetColors, savedColors: savedColorsProp, onSavedColorsChange, defaultMode = 'solid', mode: modeProp, onModeChange, gradientValue: gradientProp, onGradientChange, size = 'md', state = 'default', disabled = false, label, helperText, errorMessage, required = false, theme, className, id, children, ...props }, ref) => {
     const generatedId = React__default.useId();
     const componentId = id || generatedId;
     const stopIdRef = useRef(0);
+    // errorMessage takes precedence over helperText while invalid; helperText
+    // behavior is unchanged otherwise.
+    const displayedMessage = state === 'invalid' && errorMessage ? errorMessage : helperText;
+    const describedById = displayedMessage ? `${componentId}-helper` : undefined;
     // Parse initial color value
     const initialColor = useMemo(() => {
-        const parsed = parseColor(value || defaultValue);
+        const initial = value || defaultValue;
+        const parsed = initial && !isGradientString(initial) ? parseColor(initial) : null;
         return parsed || { h: 0, s: 0, l: 0, a: 1 };
     }, [value, defaultValue]);
     const [color, setColor] = useState(initialColor);
@@ -112,9 +124,9 @@ const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000
     const removeSavedColor = useCallback((index) => {
         setSavedColors(savedColors.filter((_, i) => i !== index));
     }, [savedColors, setSavedColors]);
-    // Update color when controlled value changes
+    // Update color when controlled value changes (skip gradient/image values — not solid colors)
     useEffect(() => {
-        if (value !== undefined) {
+        if (value !== undefined && !isGradientString(value)) {
             const parsed = parseColor(value);
             if (parsed) {
                 setColor(parsed);
@@ -201,6 +213,8 @@ const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000
         removeGradientStop,
         isOpen,
         setIsOpen,
+        describedById,
+        dialogId: `${componentId}-dialog`,
         triggerRef,
         placement: 'bottom-start',
         offset: 4,
@@ -238,6 +252,8 @@ const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000
         removeGradientStop,
         isOpen,
         setIsOpen,
+        describedById,
+        componentId,
         showAlpha,
         showEyeDropper,
         presetColors,
@@ -255,7 +271,7 @@ const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000
         addSavedColor,
         removeSavedColor,
     ]);
-    return (jsx(ColorPickerContext.Provider, { value: contextValue, children: jsxs("div", { ref: ref, className: cn(mergedTheme.baseStyle, className), ...props, children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: componentId, required: required, state: state, children: label })) : (label)), children, helperText && (typeof helperText === 'string' ? (jsx("div", { id: `${componentId}-helper`, className: cn('mt-1.5 text-sm text-[var(--color-text-secondary)]', state === 'invalid' && 'text-[var(--color-danger)]'), children: helperText })) : (helperText))] }) }));
+    return (jsx(ColorPickerContext.Provider, { value: contextValue, children: jsxs("div", { ref: ref, className: cn(mergedTheme.baseStyle, className), ...props, children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: componentId, required: required, state: state, children: label })) : (label)), children, displayedMessage && (typeof displayedMessage === 'string' ? (jsx("div", { id: `${componentId}-helper`, role: state === 'invalid' ? 'alert' : undefined, className: cn('mt-1.5 text-sm text-[var(--color-text-secondary)]', state === 'invalid' && 'text-[var(--color-danger)]'), children: displayedMessage })) : (displayedMessage))] }) }));
 });
 ColorPickerRoot.displayName = 'ColorPicker';
 /**

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

@@ -88,6 +88,12 @@ export interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivEleme
      * Helper text displayed below the picker
      */
     helperText?: React.ReactNode;
+    /**
+     * Error message shown instead of `helperText` when `state="invalid"`.
+     * Takes precedence over `helperText` while invalid; `helperText` is
+     * unaffected/still shown as normal otherwise.
+     */
+    errorMessage?: React.ReactNode;
     /**
      * Whether the picker is required
      * @default false
@@ -148,6 +154,8 @@ export interface ColorPickerContextValue {
     removeGradientStop: (id: string) => void;
     isOpen: boolean;
     setIsOpen: (open: boolean) => void;
+    describedById?: string;
+    dialogId: string;
     triggerRef: React.RefObject<HTMLElement>;
     placement: import("../../../hooks/useSelectPortal").SelectPlacement;
     offset: number;

package/dist/components/forms/ColorPicker/ColorPicker2DCanvas.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { useContext, useRef, useState, useCallback, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';

package/dist/components/forms/ColorPicker/ColorPickerBody.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
 import { useContext, useRef, useEffect } from 'react';
@@ -21,7 +22,7 @@ const ColorPickerBody = ({ children, className, portal = true, animation = true,
     if (!context) {
         throw new Error('ColorPicker.Body must be used within a ColorPicker');
     }
-    const { isOpen, setIsOpen, theme, triggerRef, placement, offset } = context;
+    const { isOpen, setIsOpen, theme, triggerRef, placement, offset, dialogId } = context;
     // Use positioning hook (same as Dropdown/Select)
     const { position, cssVariables } = useSelectPortal({
         triggerRef,
@@ -54,7 +55,7 @@ const ColorPickerBody = ({ children, className, portal = true, animation = true,
     }, [isOpen, setIsOpen, triggerRef]);
     // Extract DOM event handler props that conflict with Framer Motion
     const { onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, ...domProps } = rest;
-    const content = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: contentRef, role: "dialog", "aria-label": "Color picker", className: cn('fixed z-50', theme.contentStyle, className), style: {
+    const content = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: contentRef, id: dialogId, role: "dialog", "aria-label": "Color picker", className: cn('fixed z-50', theme.contentStyle, className), style: {
                 ...cssVariables,
                 top: `${position.top}px`,
                 left: `${position.left}px`,

package/dist/components/forms/ColorPicker/ColorPickerContext.js

@@ -1,3 +1,4 @@
+"use client";
 import React__default, { createContext } from 'react';
 
 const ColorPickerContext = createContext(undefined);

package/dist/components/forms/ColorPicker/ColorPickerEyeDropper.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { EyeDropperIcon } from '@heroicons/react/20/solid';
 import { useContext, useMemo } from 'react';

package/dist/components/forms/ColorPicker/ColorPickerFormatSelector.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { useContext } from 'react';
 import { cn } from '../../../utils/cn.js';

package/dist/components/forms/ColorPicker/ColorPickerGradient.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { TrashIcon, PlusIcon, ClipboardDocumentCheckIcon, ClipboardDocumentIcon } from '@heroicons/react/20/solid';
 import { useContext, useState, useRef, useCallback, useEffect } from 'react';

package/dist/components/forms/ColorPicker/ColorPickerHeader.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { XMarkIcon } from '@heroicons/react/20/solid';
 import { useContext } from 'react';

package/dist/components/forms/ColorPicker/ColorPickerImage.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { ArrowUpTrayIcon, XMarkIcon } from '@heroicons/react/20/solid';
 import { useContext, useRef, useState, useEffect, useCallback } from 'react';

package/dist/components/forms/ColorPicker/ColorPickerInput.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { useContext, useState, useEffect } from 'react';
 import { ChevronUpDownIcon, ClipboardDocumentCheckIcon, ClipboardDocumentIcon } from '@heroicons/react/20/solid';

package/dist/components/forms/ColorPicker/ColorPickerPresets.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { useContext } from 'react';
 import { CheckIcon } from '@heroicons/react/16/solid';

package/dist/components/forms/ColorPicker/ColorPickerSavedColors.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { PlusIcon } from '@heroicons/react/20/solid';
 import { useContext } from 'react';

package/dist/components/forms/ColorPicker/ColorPickerSliders.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { useContext, useMemo, useRef, useState, useCallback, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';

package/dist/components/forms/ColorPicker/ColorPickerSwatch.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { useContext } from 'react';
 import { cn } from '../../../utils/cn.js';

package/dist/components/forms/ColorPicker/ColorPickerTrigger.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { useContext, useRef, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -17,7 +18,7 @@ const ColorPickerTrigger = ({ className, ...props }) => {
     if (!context) {
         throw new Error('ColorPickerTrigger must be used within a ColorPicker');
     }
-    const { isOpen, setIsOpen, disabled, state, mode, gradient, getFormattedValue, triggerRef } = context;
+    const { isOpen, setIsOpen, disabled, state, mode, gradient, getFormattedValue, triggerRef, describedById, dialogId } = context;
     // Display value: for gradient mode, show stop colors comma-separated
     const displayValue = mode === 'gradient'
         ? [...gradient.stops].sort((a, b) => a.position - b.position).map(s => s.color).join(', ')
@@ -35,7 +36,21 @@ const ColorPickerTrigger = ({ className, ...props }) => {
             setIsOpen(!isOpen);
         }
     };
-    return (jsx("div", { ref: wrapperRef, onClick: handleWrapperClick, className: "relative", children: jsx(Input, { ref: inputRef, value: displayValue, readOnly: true, disabled: disabled, state: state, contentStart: jsx(ColorPickerSwatch, { size: "sm" }), className: cn('cursor-pointer pointer-events-none', className), "aria-expanded": isOpen, "aria-haspopup": "dialog", ...props }) }));
+    // Keyboard access: the readOnly input is the focusable trigger, but clicks are
+    // handled by the wrapper — so wire Enter/Space/ArrowDown to open and Escape to close
+    // (preventDefault stops Space from scrolling / Enter from submitting a form).
+    const handleKeyDown = (e) => {
+        if (disabled)
+            return;
+        if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+            e.preventDefault();
+            setIsOpen(true);
+        }
+        else if (e.key === "Escape" && isOpen) {
+            setIsOpen(false);
+        }
+    };
+    return (jsx("div", { ref: wrapperRef, onClick: handleWrapperClick, className: "relative", children: jsx(Input, { ref: inputRef, value: displayValue, readOnly: true, disabled: disabled, state: state, contentStart: jsx(ColorPickerSwatch, { size: "sm" }), className: cn('cursor-pointer pointer-events-none', className), role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "dialog", "aria-controls": dialogId, "aria-describedby": describedById, onKeyDown: handleKeyDown, ...props }) }));
 };
 ColorPickerTrigger.displayName = 'ColorPickerTrigger';
 

package/dist/components/forms/Combobox/Combobox.js

@@ -1,8 +1,9 @@
+"use client";
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import React__default, { useId, useRef, useEffect, useCallback } from 'react';
+import React__default, { useId, useRef, useState, useEffect, useCallback } from 'react';
 import { AnimatePresence, motion } from 'motion/react';
 import { createPortal } from 'react-dom';
-import { XMarkIcon, PlusIcon } from '@heroicons/react/24/outline';
+import { XMarkIcon, PlusIcon, CheckIcon } from '@heroicons/react/24/outline';
 import { comboboxTheme } from './Combobox.theme.js';
 import { FormLabel } from '../FormLabel/FormLabel.js';
 import { createDropdownAnimations } from '../Select/Select.animations.js';
@@ -12,6 +13,7 @@ import { SelectProvider, useSelectContext } from '../Select/Select.js';
 import '../Select/Select.theme.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
 import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 import { useSelectState } from '../Select/useSelectState.js';
 
 /**
@@ -20,8 +22,11 @@ import { useSelectState } from '../Select/useSelectState.js';
 const defaultFilterFn = (option, inputValue) => {
     return option.label.toLowerCase().includes(inputValue.toLowerCase());
 };
-const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offset, emptyMessage, className, listboxId, comboboxId, }) => {
+const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offset, emptyMessage, className, listboxId, comboboxId, elevation, lift, }) => {
     var _a;
+    // Relative elevation: the listbox lifts above its host surface (overlay base = 5)
+    // so a Combobox inside a Popover/Modal still reads as a higher plane.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const { filteredOptions, highlightedIndex, setHighlightedIndex, selectedValue, selectOption, optionsRef, theme, } = useSelectContext();
     const isDarkMode = useDarkMode();
     const isClient = useIsClient();
@@ -78,7 +83,7 @@ const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offse
     const disabledOptionStyle = theme.disabledOptionStyle || comboboxTheme.disabledOptionStyle;
     const createOptionStyleTheme = theme.createOptionStyle || comboboxTheme.createOptionStyle;
     const emptyMessageStyle = comboboxTheme.emptyMessageStyle;
-    const optionsContent = (jsx(AnimatePresence, { mode: "wait", children: isOpen && (jsx(motion.div, { ref: combinedRef, id: listboxId, role: "listbox", className: cn(dropdownStyle, className), style: {
+    const optionsContent = (jsx(AnimatePresence, { mode: "wait", children: isOpen && (jsx(motion.div, { ref: combinedRef, id: listboxId, role: "listbox", className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: true }), dropdownStyle, className), style: {
                 ...cssVariables,
                 overscrollBehavior: "contain",
                 ...(portal
@@ -88,17 +93,19 @@ const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offse
                         width: `${position.width}px`,
                     }
                     : {}),
-            }, tabIndex: -1, variants: animations, initial: "initial", animate: "visible", exit: "exit", children: filteredOptions.length === 0 ? (jsx("div", { className: emptyMessageStyle, children: emptyMessage })) : (jsxs(Fragment, { children: [(filteredOptions.length > 100 ? filteredOptions.slice(0, 100) : filteredOptions).map((option, index) => {
-                        const isSelected = option.value === selectedValue;
-                        const isHighlighted = index === highlightedIndex;
-                        const isCreateOption = option.id === "__create__";
-                        return (jsx("div", { id: comboboxId ? `${comboboxId}-option-${option.id}` : undefined, role: "option", "aria-selected": isSelected, "aria-disabled": option.disabled, "data-option-index": index, className: cn(optionStyle, isSelected && selectedOptionStyle, isHighlighted && highlightedOptionStyle, option.disabled && disabledOptionStyle, isCreateOption && createOptionStyleTheme), onMouseEnter: () => !option.disabled && setHighlightedIndex(index), onClick: () => {
-                                if (!option.disabled) {
-                                    selectOption(option.value, isCreateOption);
-                                    onClose();
-                                }
-                            }, children: isCreateOption ? (jsxs("span", { className: "flex items-center gap-1", children: [jsx(PlusIcon, { className: "size-4 shrink-0", strokeWidth: 2 }), jsx("span", { className: "block truncate", children: option.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"] }))] })) })) }));
+            }, tabIndex: -1, variants: animations, initial: "initial", animate: "visible", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: filteredOptions.length === 0 ? (jsx("div", { className: emptyMessageStyle, children: emptyMessage })) : (jsxs(Fragment, { children: [(filteredOptions.length > 100 ? filteredOptions.slice(0, 100) : filteredOptions).map((option, index) => {
+                            const isSelected = option.value === selectedValue;
+                            const isHighlighted = index === highlightedIndex;
+                            const isCreateOption = option.id === "__create__";
+                            return (jsxs("div", { id: comboboxId ? `${comboboxId}-option-${option.id}` : undefined, role: "option", "aria-selected": isSelected, "aria-disabled": option.disabled, "data-option-index": index, className: cn(optionStyle, isSelected && selectedOptionStyle, 
+                                // Reserve room on the right so a long, truncated label never runs under the check.
+                                isSelected && !isCreateOption && "pr-9", isHighlighted && highlightedOptionStyle, option.disabled && disabledOptionStyle, isCreateOption && createOptionStyleTheme), onMouseEnter: () => !option.disabled && setHighlightedIndex(index), onClick: () => {
+                                    if (!option.disabled) {
+                                        selectOption(option.value, isCreateOption);
+                                        onClose();
+                                    }
+                                }, children: [isCreateOption ? (jsxs("span", { className: "flex items-center gap-1", children: [jsx(PlusIcon, { className: "size-4 shrink-0", strokeWidth: 2 }), jsx("span", { className: "block truncate", children: option.label })] })) : (jsx("span", { className: "block truncate", children: option.label })), isSelected && !isCreateOption && (jsx("span", { className: "absolute inset-y-0 right-0 flex items-center pr-3 text-[var(--color-primary)] dark:text-[var(--color-primary-400)]", children: jsx(CheckIcon, { className: "size-4", strokeWidth: 2 }) }))] }, 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"] }))] })) }) })) }));
     if (portal && isClient) {
         return createPortal(jsx("div", { "data-flikkui-portal": "", className: isDarkMode ? "dark" : undefined, children: optionsContent }), document.body);
     }
@@ -126,7 +133,7 @@ const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offse
  * />
  * ```
  */
-const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", label, helperText, size = "md", state = "default", clearable = true, iconStart, iconEnd, openOnFocus = true, filterFn = defaultFilterFn, emptyMessage = "No results found", creatable = false, onCreateOption, createLabel, required = false, name, className, wrapperClassName, inputClassName, dropdownClassName, theme: themeOverrides, portal = true, placement = "bottom-start", offset = 8, id, ...props }, ref) => {
+const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", label, helperText, size = "md", state = "default", clearable = true, iconStart, iconEnd, openOnFocus = true, filterFn = defaultFilterFn, emptyMessage = "No results found", creatable = false, onCreateOption, createLabel, required = false, name, className, wrapperClassName, inputClassName, dropdownClassName, theme: themeOverrides, portal = true, placement = "bottom-start", offset = 8, elevation, lift, id, ...props }, ref) => {
     var _a;
     // Merge theme
     const theme = React__default.useMemo(() => ({ ...comboboxTheme, ...(themeOverrides || {}) }), [themeOverrides]);
@@ -138,6 +145,18 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
     const inputRef = useRef(null);
     const wrapperRef = useRef(null);
     const justSelectedRef = useRef(false);
+    const prevOpenRef = useRef(false);
+    // Whether the visible text should be treated as a live filter query.
+    //
+    // The input's displayed text (`searchValue`) does double duty: while the
+    // control is closed it echoes the *selected label* so the field reads
+    // "TypeScript", and while open+typing it is the *filter query*. Filtering on
+    // that same value the instant the listbox opens narrows the list to the one
+    // already-selected match — so opening to *change* a selection shows a single
+    // row instead of the full list. We gate filtering on `isFiltering`: the list
+    // stays full on open (matching Select and the WAI-ARIA editable-combobox
+    // pattern) and only filters once the user actually types.
+    const [isFiltering, setIsFiltering] = useState(false);
     // Convert ComboboxOption to SelectOption format
     const selectOptions = React__default.useMemo(() => options.map((opt) => ({
         id: opt.id,
@@ -145,13 +164,6 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
         value: opt.value,
         disabled: opt.disabled,
     })), [options]);
-    // Custom filter wrapper - filter options before passing to useSelectState
-    // This allows us to use the custom filterFn prop
-    selectOptions.filter((opt) => {
-        // If there's no search value in the internal state yet, return all
-        // We'll handle filtering via searchValue from selectState
-        return true; // Let useSelectState handle filtering
-    });
     // Use the shared select state hook
     const selectState = useSelectState({
         options: selectOptions,
@@ -164,38 +176,43 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
         onCreateOption,
         createLabel,
     });
-    const { isOpen, setIsOpen, searchValue, setSearchValue, highlightedIndex, setHighlightedIndex, filteredOptions: baseFilteredOptions, selectedOption, selectOption, } = selectState;
+    const { isOpen, setIsOpen, searchValue, setSearchValue, highlightedIndex, setHighlightedIndex, selectedOption, selectOption, } = selectState;
+    // The live filter query. Empty until the user types (`isFiltering`), so the
+    // listbox opens on the full option set even when a value is already selected
+    // (its label is sitting in `searchValue` for display only). `baseFilteredOptions`
+    // is intentionally unused here — the query gate replaces useSelectState's own
+    // label-based filtering.
+    const effectiveQuery = isFiltering ? searchValue : "";
     // Apply custom filter function if provided (override the default filtering)
     const customFilteredOptions = React__default.useMemo(() => {
-        if (!searchValue)
-            return baseFilteredOptions;
+        if (!effectiveQuery)
+            return selectOptions;
         // Re-filter using custom filterFn
-        const refiltered = selectOptions.filter((option) => filterFn(option, searchValue));
+        const refiltered = selectOptions.filter((option) => filterFn(option, effectiveQuery));
         // Check if we should show create option
         const shouldShowCreate = creatable &&
-            searchValue.trim() !== "" &&
-            !refiltered.some((option) => option.label.toLowerCase() === searchValue.toLowerCase());
+            effectiveQuery.trim() !== "" &&
+            !refiltered.some((option) => option.label.toLowerCase() === effectiveQuery.toLowerCase());
         if (shouldShowCreate) {
             const createOptionLabel = typeof createLabel === "function"
-                ? createLabel(searchValue)
-                : createLabel || `Create "${searchValue}"`;
+                ? createLabel(effectiveQuery)
+                : createLabel || `Create "${effectiveQuery}"`;
             return [
                 {
                     id: "__create__",
                     label: createOptionLabel,
-                    value: searchValue,
+                    value: effectiveQuery,
                 },
                 ...refiltered,
             ];
         }
         return refiltered;
     }, [
-        searchValue,
+        effectiveQuery,
         selectOptions,
         filterFn,
         creatable,
         createLabel,
-        baseFilteredOptions,
     ]);
     // Derived state
     const isDisabled = state === "disabled";
@@ -209,10 +226,29 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
             setSearchValue("");
         }
     }, [isOpen, selectedOption, value, setSearchValue]);
-    // Reset highlighted index when options change
+    // Reset highlighted index as the filter query changes the option set.
     useEffect(() => {
         setHighlightedIndex(-1);
-    }, [customFilteredOptions.length, searchValue, setHighlightedIndex]);
+    }, [customFilteredOptions.length, effectiveQuery, setHighlightedIndex]);
+    // On the closed→open transition, pre-highlight the current selection so
+    // keyboard nav starts there and it scrolls into view within the full list.
+    // (Only on the transition — not while typing, where the reset above owns the
+    // index.) Reset the filter gate whenever the listbox closes so the next open
+    // always starts on the full list, regardless of how it closed (click-outside,
+    // Escape, Tab, selection).
+    useEffect(() => {
+        const justOpened = isOpen && !prevOpenRef.current;
+        prevOpenRef.current = isOpen;
+        if (!isOpen) {
+            setIsFiltering(false);
+            return;
+        }
+        if (justOpened && !isFiltering && selectedOption) {
+            const idx = selectOptions.findIndex((o) => o.value === selectedOption.value);
+            if (idx >= 0)
+                setHighlightedIndex(idx);
+        }
+    }, [isOpen, isFiltering, selectedOption, selectOptions, setHighlightedIndex]);
     // Handle clear
     const handleClear = useCallback((e) => {
         var _a;
@@ -227,6 +263,8 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
     const handleInputChange = useCallback((e) => {
         const newValue = e.target.value;
         setSearchValue(newValue);
+        // A keystroke turns the visible text into a live filter query.
+        setIsFiltering(true);
         // Open dropdown when typing
         if (!isOpen && newValue) {
             setIsOpen(true);
@@ -238,13 +276,19 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
     }, [isOpen, value, onChange, setSearchValue, setIsOpen]);
     // Handle input focus
     const handleInputFocus = useCallback(() => {
+        var _a;
         // Skip reopening if we just selected an option
         if (justSelectedRef.current) {
             justSelectedRef.current = false;
             return;
         }
         if (openOnFocus && !isDisabled) {
+            // Open on the full list (not pre-filtered to the current value) and
+            // select the displayed label so the first keystroke replaces it —
+            // matching the browser address-bar / Select behavior.
+            setIsFiltering(false);
             setIsOpen(true);
+            (_a = inputRef.current) === null || _a === void 0 ? void 0 : _a.select();
         }
     }, [openOnFocus, isDisabled, setIsOpen]);
     // Handle option selection
@@ -370,7 +414,7 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
     return (jsx(SelectProvider, { selectState: modifiedSelectState, size: size, componentState: state, theme: theme, searchable: true, enableTypeahead: false, children: jsxs("div", { ref: ref, className: cn("relative", containerClasses, stateClass, wrapperClassName), ...props, children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: comboboxId, state: state, required: required, children: label })) : (label)), jsxs("div", { ref: wrapperRef, className: theme.wrapperStyle, children: [jsx("div", { className: cn(inputGroupClasses, stateClasses, className), children: jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: inputRef, id: comboboxId, type: "text", role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": listboxId, "aria-activedescendant": highlightedIndex >= 0 &&
                                             customFilteredOptions[highlightedIndex]
                                             ? `${comboboxId}-option-${customFilteredOptions[highlightedIndex].id}`
-                                            : undefined, "aria-autocomplete": "list", "aria-invalid": isInvalid, "aria-describedby": helperText ? `${comboboxId}-helper` : undefined, autoComplete: "off", className: cn(inputClasses, sizeClasses, iconStartPadding, (hasRightIcon || showClearButton) && iconEndPadding, showClearButton && "pr-8", inputClassName), value: searchValue, onChange: handleInputChange, onFocus: handleInputFocus, onKeyDown: handleKeyDown, placeholder: placeholder, disabled: isDisabled, required: required }), hasLeftIcon && (jsx("div", { className: theme.iconStartStyle, children: iconStart })), showClearButton && (jsx("button", { type: "button", className: theme.clearButtonStyle, onClick: handleClear, "aria-label": "Clear selection", tabIndex: -1, children: jsx(XMarkIcon, { className: theme.clearIconStyle }) })), hasRightIcon && !showClearButton && (jsx("div", { className: theme.iconEndStyle, children: iconEnd }))] }) }), jsx(ComboboxOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), triggerRef: wrapperRef, portal: portal, placement: placement, offset: offset, emptyMessage: emptyMessage, className: dropdownClassName, listboxId: listboxId, comboboxId: comboboxId })] }), helperText && (typeof helperText === 'string' ? (jsx("p", { id: `${comboboxId}-helper`, className: cn(helperTextClasses, helperTextStateClasses), children: helperText })) : (helperText)), name && (jsx("input", { type: "hidden", name: name, value: value !== undefined ? String(value) : "" }))] }) }));
+                                            : undefined, "aria-autocomplete": "list", "aria-invalid": isInvalid, "aria-describedby": helperText ? `${comboboxId}-helper` : undefined, autoComplete: "off", className: cn(inputClasses, sizeClasses, iconStartPadding, (hasRightIcon || showClearButton) && iconEndPadding, showClearButton && "pr-8", inputClassName), value: searchValue, onChange: handleInputChange, onFocus: handleInputFocus, onKeyDown: handleKeyDown, placeholder: placeholder, disabled: isDisabled, required: required }), hasLeftIcon && (jsx("div", { className: theme.iconStartStyle, children: iconStart })), showClearButton && (jsx("button", { type: "button", className: theme.clearButtonStyle, onClick: handleClear, "aria-label": "Clear selection", tabIndex: -1, children: jsx(XMarkIcon, { className: theme.clearIconStyle }) })), hasRightIcon && !showClearButton && (jsx("div", { className: theme.iconEndStyle, children: iconEnd }))] }) }), jsx(ComboboxOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), triggerRef: wrapperRef, portal: portal, placement: placement, offset: offset, emptyMessage: emptyMessage, className: dropdownClassName, listboxId: listboxId, comboboxId: comboboxId, elevation: elevation, lift: lift })] }), helperText && (typeof helperText === 'string' ? (jsx("p", { id: `${comboboxId}-helper`, className: cn(helperTextClasses, helperTextStateClasses), children: helperText })) : (helperText)), name && (jsx("input", { type: "hidden", name: name, value: value !== undefined ? String(value) : "" }))] }) }));
 };
 const ComboboxForwarded = React__default.forwardRef(ComboboxInner);
 ComboboxForwarded.displayName = "Combobox";

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 /**
  * Individual option for Combobox
  */
@@ -76,6 +77,13 @@ export interface ComboboxProps<T = string> extends Omit<React.HTMLAttributes<HTM
     placement?: "bottom-start" | "bottom-end" | "top-start" | "top-end";
     /** Offset from trigger */
     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;
 }
 /**
  * Theme configuration for Combobox

package/dist/components/forms/DatePicker/DatePicker.animations.js

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Creates direction-aware dropdown animation variants for the DatePicker component
  * Matches Select component animation pattern for consistency

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

@@ -1,34 +1,10 @@
 import React from "react";
-import type { DatePickerProps, DatePickerState, DatePickerSize, DateRange, DatePickerMode, DatePickerTheme } from "./DatePicker.types";
+import type { DatePickerProps } from "./DatePicker.types";
 import { DatePickerTrigger } from "./DatePickerTrigger";
 import { DatePickerBody } from "./DatePickerBody";
 import { DatePickerPresets } from "./DatePickerPresets";
-interface DatePickerContextType {
-    mode: DatePickerMode;
-    isOpen: boolean;
-    setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
-    selectedValue: Date | DateRange | undefined;
-    setSelectedValue: React.Dispatch<React.SetStateAction<Date | DateRange | undefined>>;
-    minDate?: Date;
-    maxDate?: Date;
-    isDateDisabled?: (date: Date) => boolean;
-    showToday?: boolean;
-    selectTodayByDefault?: boolean;
-    weekdays?: string[];
-    months?: string[];
-    yearRange?: {
-        start: number;
-        end: number;
-    };
-    handleDateSelect: (date: Date) => void;
-    handleRangeSelect?: (range: DateRange) => void;
-    size: DatePickerSize;
-    state: DatePickerState;
-    theme: DatePickerTheme;
-    triggerRef: React.RefObject<HTMLButtonElement | null>;
-    contentRef: React.RefObject<HTMLDivElement | null>;
-}
-export declare const DatePickerContext: React.Context<DatePickerContextType | undefined>;
+import { DatePickerContext } from "./DatePickerContext";
+export { DatePickerContext };
 /**
  * Main DatePicker Component - follows Select pattern exactly
  */

package/dist/components/forms/DatePicker/DatePicker.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import React__default, { createContext, useState, useRef, useEffect, useCallback, useMemo } from 'react';
+import React__default, { useState, useRef, useEffect, useCallback, useMemo } from 'react';
 import { datePickerTheme } from './DatePicker.theme.js';
 import { FormLabel } from '../FormLabel/FormLabel.js';
 import { DatePickerTrigger } from './DatePickerTrigger.js';
@@ -7,8 +8,8 @@ import { DatePickerBody } from './DatePickerBody.js';
 import { DatePickerPresets } from './DatePickerPresets.js';
 import { cn } from '../../../utils/cn.js';
 import { formatDateCustom } from '../../../utils/dateUtils.js';
+import { DatePickerContext } from './DatePickerContext.js';
 
-const DatePickerContext = createContext(undefined);
 /**
  * Format date for display
  * Uses formatString if provided, otherwise falls back to dateFormat (Intl API)
@@ -43,7 +44,7 @@ const formatDateRange = (range, formatString, options) => {
 /**
  * Main DatePicker Component - follows Select pattern exactly
  */
-const DatePickerComponent = React__default.forwardRef(({ id, name, mode = "single", size = "md", state = "default", value, defaultValue, placeholder = "Select date...", disabled = false, required = false, label, helperText, onChange, onFocus, onBlur, minDate, maxDate, isDateDisabled, showToday = true, selectTodayByDefault = false, weekdays, months, dateFormat, formatString, yearRange, presets, className = "", wrapperClassName = "", portal = true, placement = "bottom-start", offset = 4, children, }, ref) => {
+const DatePickerComponent = React__default.forwardRef(({ id, name, mode = "single", size = "md", state = "default", value, defaultValue, placeholder = "Select date...", disabled = false, required = false, label, helperText, onChange, onFocus, onBlur, minDate, maxDate, isDateDisabled, showToday = true, selectTodayByDefault = false, weekdays, months, dateFormat, formatString, yearRange, presets, className = "", wrapperClassName = "", portal = true, placement = "bottom-start", offset = 4, elevation, lift, children, }, ref) => {
     var _a, _b;
     // Merge theme with defaults
     const theme = { ...datePickerTheme };
@@ -120,7 +121,7 @@ const DatePickerComponent = React__default.forwardRef(({ id, name, mode = "singl
             theme,
             triggerRef,
             contentRef,
-        }), [mode, isOpen, selectedValue, minDate, maxDate, isDateDisabled, showToday, selectTodayByDefault, weekdays, months, yearRange, handleDateSelect, handleRangeSelect, size, state, theme]), children: jsxs("div", { ref: ref, className: cn(containerStyle, wrapperClassName), children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: datePickerId, state: state, required: required, children: label })) : (label)), jsx(DatePickerTrigger, { id: datePickerId, disabled: disabled, isOpen: isOpen, state: state, size: size, onClick: handleButtonClick, onFocus: onFocus, onBlur: onBlur, className: className, "aria-invalid": state === 'invalid' || undefined, "aria-describedby": helperText ? `${datePickerId}-helper` : undefined, children: jsx("span", { className: cn("block truncate", selectedValue ? theme.valueTextStyle : theme.placeholderTextStyle), children: displayValue }) }), jsx(DatePickerBody, { isOpen: isOpen, onClose: () => setIsOpen(false), portal: portal, placement: placement, offset: offset, presets: presets, children: children }), helperText && (typeof helperText === 'string' ? (jsx("p", { id: `${datePickerId}-helper`, className: cn(helperTextStyle, helperTextStateStyle), children: helperText })) : (helperText)), name && mode === "single" && selectedValue instanceof Date && (jsx("input", { type: "hidden", name: name, value: selectedValue.toISOString() })), name &&
+        }), [mode, isOpen, selectedValue, minDate, maxDate, isDateDisabled, showToday, selectTodayByDefault, weekdays, months, yearRange, handleDateSelect, handleRangeSelect, size, state, theme]), children: jsxs("div", { ref: ref, className: cn(containerStyle, wrapperClassName), children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: datePickerId, state: state, required: required, children: label })) : (label)), jsx(DatePickerTrigger, { id: datePickerId, disabled: disabled, isOpen: isOpen, state: state, size: size, onClick: handleButtonClick, onFocus: onFocus, onBlur: onBlur, className: className, "aria-invalid": state === 'invalid' || undefined, "aria-describedby": helperText ? `${datePickerId}-helper` : undefined, children: jsx("span", { className: cn("block truncate", selectedValue ? theme.valueTextStyle : theme.placeholderTextStyle), children: displayValue }) }), jsx(DatePickerBody, { isOpen: isOpen, onClose: () => setIsOpen(false), portal: portal, placement: placement, offset: offset, presets: presets, elevation: elevation, lift: lift, children: children }), helperText && (typeof helperText === 'string' ? (jsx("p", { id: `${datePickerId}-helper`, className: cn(helperTextStyle, helperTextStateStyle), children: helperText })) : (helperText)), name && mode === "single" && selectedValue instanceof Date && (jsx("input", { type: "hidden", name: name, value: selectedValue.toISOString() })), name &&
                     mode === "range" &&
                     selectedValue &&
                     typeof selectedValue === "object" &&

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

@@ -10,8 +10,8 @@ import { formsBaseTheme } from '../forms.theme.js';
 const datePickerTheme = {
     containerStyle: formsBaseTheme.wrapperStyle,
     baseStyle: formsBaseTheme.inputGroupBaseStyle + " justify-between cursor-pointer",
-    // Trigger button style - surface flips automatically between light/dark
-    triggerButtonStyle: "w-full cursor-pointer bg-[var(--color-surface)]",
+    // Trigger button style — field fill lifts one rung above the host surface (via --field-fill)
+    triggerButtonStyle: "w-full cursor-pointer bg-[var(--field-fill)]",
     // Placeholder text style - matches Input placeholder styling
     placeholderTextStyle: "text-[var(--color-text-placeholder)]",
     // Selected value text style
@@ -26,9 +26,9 @@ const datePickerTheme = {
     triggerFocusStates: formsBaseTheme.focusStates,
     iconEndStyle: formsBaseTheme.iconStyles.right,
     iconEndPadding: formsBaseTheme.iconStyles.padding.right,
-    // Dropdown body - floating overlay surface flips automatically
-    bodyStyle: "min-w-fit max-w-none bg-[var(--color-surface-overlay)]/80 backdrop-blur-md border border-[var(--color-border)] rounded-[var(--popover-radius)] shadow-real-xl p-0 overflow-hidden z-[1000] fixed",
-    bodyWithPresetsStyle: "flex flex-col sm:flex-row w-fit max-w-[calc(100vw-2rem)] sm:max-w-none bg-[var(--color-surface-overlay)]/80 backdrop-blur-md border border-[var(--color-border)] rounded-[var(--popover-radius)] shadow-lg p-0 overflow-hidden z-[1000] fixed",
+    // Dropdown body - surface painted by the relative-elevation engine (surfaceClasses)
+    bodyStyle: "min-w-fit max-w-none backdrop-blur-md border border-[var(--color-border)] rounded-[var(--popover-radius)] p-0 overflow-hidden z-[1000] fixed",
+    bodyWithPresetsStyle: "flex flex-col sm:flex-row w-fit max-w-[calc(100vw-2rem)] sm:max-w-none backdrop-blur-md border border-[var(--color-border)] rounded-[var(--popover-radius)] shadow-lg p-0 overflow-hidden z-[1000] fixed",
     // Presets sidebar - recessed sunken panel flips automatically
     presetsContainerStyle: "flex flex-col gap-1 p-3 border-b sm:border-b-0 sm:border-r border-[var(--color-border)] bg-[var(--color-surface-sunken)] sm:min-w-[180px]",
     // Preset button - surface hover/active fills flip automatically