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

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

@@ -1,8 +1,9 @@
-import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { useId, useRef, useEffect, useCallback } from 'react';
+"use client";
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+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';
@@ -11,44 +12,21 @@ import { cn } from '../../../utils/cn.js';
 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';
 
-/**
- * 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();
-        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;
-};
 /**
  * Default filter function for options
  */
 const defaultFilterFn = (option, inputValue) => {
     return option.label.toLowerCase().includes(inputValue.toLowerCase());
 };
-const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offset, emptyMessage, className, }) => {
+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();
@@ -95,7 +73,8 @@ const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offse
         return () => document.removeEventListener("mousedown", handleClickOutside);
     }, [isOpen, onClose, portal, contentRef, optionsRef, triggerRef]);
     // Theme can come from Select's theme (optionsContainerStyle) or Combobox's theme (dropdownStyle)
-    const dropdownStyle = theme.dropdownStyle ||
+    const comboboxThemeRef = theme;
+    const dropdownStyle = comboboxThemeRef.dropdownStyle ||
         theme.optionsContainerStyle ||
         comboboxTheme.dropdownStyle;
     const optionStyle = theme.optionStyle || comboboxTheme.optionStyle;
@@ -104,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, 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
@@ -114,19 +93,21 @@ 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 })) : (filteredOptions.map((option, index) => {
-                const isSelected = option.value === selectedValue;
-                const isHighlighted = index === highlightedIndex;
-                const isCreateOption = option.id === "__create__";
-                return (jsx("div", { 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));
-            })) })) }));
+            }, 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", { 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;
 };
@@ -152,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, 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]);
@@ -164,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,
@@ -171,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,
@@ -190,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";
@@ -235,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;
@@ -253,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);
@@ -264,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
@@ -384,19 +402,22 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
     const showClearButton = clearable && value !== undefined && !isDisabled;
     // Icon padding
     const hasLeftIcon = Boolean(iconStart);
+    const hasRightIcon = Boolean(iconEnd);
     const iconStartPadding = hasLeftIcon ? theme.iconPadding.left : "";
+    const iconEndPadding = hasRightIcon ? theme.iconPadding.right : "";
     // Create a modified selectState for the provider with our custom filtered options
     const modifiedSelectState = React__default.useMemo(() => ({
         ...selectState,
         filteredOptions: customFilteredOptions,
         selectOption: handleSelectOption,
     }), [selectState, customFilteredOptions, handleSelectOption]);
-    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 && (jsx(FormLabel, { htmlFor: comboboxId, required: required, children: 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 &&
+    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, autoComplete: "off", className: cn(inputClasses, sizeClasses, iconStartPadding, 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 }) }))] }) }), jsx(ComboboxOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), triggerRef: wrapperRef, portal: portal, placement: placement, offset: offset, emptyMessage: emptyMessage, className: dropdownClassName })] }), helperText && (jsx("p", { className: cn(helperTextClasses, helperTextStateClasses), children: 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 Combobox = React__default.forwardRef(ComboboxInner);
-Combobox.displayName = "Combobox";
+const ComboboxForwarded = React__default.forwardRef(ComboboxInner);
+ComboboxForwarded.displayName = "Combobox";
+const Combobox = ComboboxForwarded;
 
 export { Combobox };

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

@@ -28,14 +28,12 @@ const comboboxTheme = {
     focusStates: formsBaseTheme.focusStates,
     // Icon positioning styles
     iconStartStyle: formsBaseTheme.iconStyles.left,
-    iconEndStyle: "absolute inset-y-0 right-0 flex items-center pr-2 pointer-events-none text-[var(--color-text-muted)] " +
-        "dark:text-[var(--color-neutral-500)]",
+    iconEndStyle: "absolute inset-y-0 right-0 flex items-center pr-2 pointer-events-none text-[var(--color-text-muted)]",
     // Icon padding configuration
     iconPadding: formsBaseTheme.iconStyles.padding,
     // Clear button styles
     clearButtonStyle: "absolute inset-y-0 right-0 flex items-center pr-2 cursor-pointer " +
-        "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors z-10 " +
-        "dark:text-[var(--color-neutral-500)] dark:hover:text-[var(--color-neutral-200)]",
+        "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors z-10",
     clearIconStyle: "size-4",
     // Dropdown styles - matches Select component for consistency
     dropdownStyle: formsBaseTheme.dropdownStyles.container + " py-1",

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
  */
@@ -33,9 +34,9 @@ export interface ComboboxProps<T = string> extends Omit<React.HTMLAttributes<HTM
     /** Placeholder text when no value is selected */
     placeholder?: string;
     /** Label text displayed above the input */
-    label?: string;
+    label?: React.ReactNode;
     /** Helper text displayed below the input */
-    helperText?: string;
+    helperText?: React.ReactNode;
     /** Size variant */
     size?: ComboboxSize;
     /** State variant (controls styling) */
@@ -44,6 +45,8 @@ export interface ComboboxProps<T = string> extends Omit<React.HTMLAttributes<HTM
     clearable?: boolean;
     /** Icon displayed at the start of the input */
     iconStart?: React.ReactNode;
+    /** Icon displayed at the end of the input */
+    iconEnd?: React.ReactNode;
     /** Whether to open dropdown on focus (default: true) */
     openOnFocus?: boolean;
     /** Custom filter function */
@@ -74,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,38 +1,18 @@
 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 { DatePickerContent } from "./DatePickerContent";
+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[];
-    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
  */
 declare const DatePickerComponent: React.ForwardRefExoticComponent<DatePickerProps & React.RefAttributes<HTMLDivElement>>;
 declare const DatePickerWithCompounds: typeof DatePickerComponent & {
     Trigger: typeof DatePickerTrigger;
-    Content: typeof DatePickerContent;
+    Body: typeof DatePickerBody;
     Presets: typeof DatePickerPresets;
 };
-export { DatePickerTrigger, DatePickerContent, DatePickerPresets, DatePickerWithCompounds as DatePicker, };
+export { DatePickerTrigger, DatePickerBody, DatePickerPresets, DatePickerWithCompounds as DatePicker, };
 export { DatePickerWithCompounds };

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

@@ -1,14 +1,15 @@
+"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';
-import { DatePickerContent } from './DatePickerContent.js';
+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)
@@ -23,7 +24,7 @@ const formatDate = (date, formatString, options = {
         return formatDateCustom(date, formatString);
     }
     // Otherwise use the Intl API
-    return date.toLocaleDateString(undefined, options);
+    return date.toLocaleDateString('en-US', options);
 };
 /**
  * Format date range for display
@@ -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, 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 };
@@ -112,6 +113,7 @@ const DatePickerComponent = React__default.forwardRef(({ id, name, mode = "singl
             selectTodayByDefault,
             weekdays,
             months,
+            yearRange,
             handleDateSelect,
             handleRangeSelect,
             size,
@@ -119,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, handleDateSelect, handleRangeSelect, size, state, theme]), children: jsxs("div", { ref: ref, className: cn(containerStyle, wrapperClassName), children: [label && (jsx(FormLabel, { htmlFor: datePickerId, required: required, children: label })), jsx(DatePickerTrigger, { id: datePickerId, disabled: disabled, isOpen: isOpen, state: state, size: size, onClick: handleButtonClick, onFocus: onFocus, onBlur: onBlur, className: className, children: jsx("span", { className: cn("block truncate", selectedValue ? theme.valueTextStyle : theme.placeholderTextStyle), children: displayValue }) }), jsx(DatePickerContent, { isOpen: isOpen, onClose: () => setIsOpen(false), portal: portal, placement: placement, offset: offset, presets: presets, children: children }), helperText && (jsx("p", { className: cn(helperTextStyle, helperTextStateStyle), children: 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" &&
@@ -130,7 +132,7 @@ DatePickerComponent.displayName = "DatePicker";
 const DatePickerWithCompounds = DatePickerComponent;
 // Attach compound components
 DatePickerWithCompounds.Trigger = DatePickerTrigger;
-DatePickerWithCompounds.Content = DatePickerContent;
+DatePickerWithCompounds.Body = DatePickerBody;
 DatePickerWithCompounds.Presets = DatePickerPresets;
 
-export { DatePickerWithCompounds as DatePicker, DatePickerContent, DatePickerContext, DatePickerPresets, DatePickerTrigger, DatePickerWithCompounds };
+export { DatePickerWithCompounds as DatePicker, DatePickerBody, DatePickerContext, DatePickerPresets, DatePickerTrigger, DatePickerWithCompounds };

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 - bg-white for light mode; dark mode uses neutral-900
-    triggerButtonStyle: "w-full cursor-pointer bg-white dark:bg-[var(--color-neutral-900)]",
+    // 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,23 +26,16 @@ const datePickerTheme = {
     triggerFocusStates: formsBaseTheme.focusStates,
     iconEndStyle: formsBaseTheme.iconStyles.right,
     iconEndPadding: formsBaseTheme.iconStyles.padding.right,
-    // Dropdown content - with dark mode support
-    contentStyle: "min-w-fit max-w-none bg-white border border-[var(--color-border)] rounded-[var(--popover-radius)] shadow-real-xl p-0 overflow-hidden z-[1000] fixed " +
-        "dark:bg-[var(--color-neutral-900)] dark:border-[var(--color-neutral-700)]",
-    contentWithPresetsStyle: "flex flex-col sm:flex-row w-fit max-w-[calc(100vw-2rem)] sm:max-w-none bg-white border border-[var(--color-border)] rounded-[var(--popover-radius)] shadow-lg p-0 overflow-hidden z-[1000] fixed " +
-        "dark:bg-[var(--color-neutral-900)] dark:border-[var(--color-neutral-700)]",
-    // Presets sidebar - with dark mode support
-    presetsContainerStyle: "flex flex-col gap-1 p-3 border-b sm:border-b-0 sm:border-r border-[var(--color-border)] bg-[var(--color-neutral-50)] sm:min-w-[180px] " +
-        "dark:bg-[var(--color-neutral-800)] dark:border-[var(--color-neutral-700)]",
-    // Preset button - with dark mode support
+    // 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
     presetButtonStyle: "w-full text-left px-3 py-2 text-sm rounded-[calc(var(--radius-base)*0.75)] transition-colors cursor-pointer " +
-        "text-[var(--color-text-secondary)] hover:bg-white hover:text-[var(--color-text-primary)] " +
-        "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 " +
-        "data-[active=true]:bg-white data-[active=true]:text-[var(--color-text-primary)] data-[active=true]:font-medium " +
-        // Dark mode
-        "dark:text-[var(--color-neutral-400)] dark:hover:bg-[var(--color-neutral-700)] dark:hover:text-[var(--color-neutral-200)] " +
-        "dark:data-[active=true]:bg-[var(--color-neutral-700)] dark:data-[active=true]:text-[var(--color-neutral-100)] " +
-        "dark:focus-visible:ring-offset-[var(--color-neutral-800)]",
+        "text-[var(--color-text-secondary)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text-primary)] " +
+        "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-surface-sunken)] " +
+        "data-[active=true]:bg-[var(--color-surface)] data-[active=true]:text-[var(--color-text-primary)] data-[active=true]:font-medium",
     helperTextStyle: formsBaseTheme.helperText,
     helperTextStates: {
         default: "text-[var(--color-text-muted)] dark:text-[var(--color-neutral-400)]",

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 /**
  * Size variants for DatePicker components
  */
@@ -49,9 +50,9 @@ export interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElemen
     /** Whether the field is required */
     required?: boolean;
     /** Label for the field */
-    label?: string;
+    label?: React.ReactNode;
     /** Helper text below the field */
-    helperText?: string;
+    helperText?: React.ReactNode;
     /** Callback fired when a date is selected - type depends on mode */
     onChange?: (value: Date | DateRange | null) => void;
     /** Array of preset date ranges (only for range mode) */
@@ -76,6 +77,11 @@ export interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElemen
     dateFormat?: Intl.DateTimeFormatOptions;
     /** Custom format string for date display (e.g., 'DD MMM YYYY', 'DD/MM/YYYY') - takes precedence over dateFormat */
     formatString?: string;
+    /** Year range for the year dropdown (default: current year back to 100 years) */
+    yearRange?: {
+        start: number;
+        end: number;
+    };
     /** Auto-select today's date when calendar opens without a value (default: false) */
     selectTodayByDefault?: boolean;
     /** Additional class name for trigger button */
@@ -88,6 +94,13 @@ export interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElemen
     placement?: DatePickerPlacement;
     /** Offset from trigger element */
     offset?: number;
+    /**
+     * Pin the popover 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 popover's base rung. */
+    lift?: boolean;
     /** Children (for compound component usage) */
     children?: React.ReactNode;
 }
@@ -105,11 +118,13 @@ export interface DatePickerTriggerProps {
     onFocus?: (event: React.FocusEvent<HTMLButtonElement>) => void;
     onBlur?: (event: React.FocusEvent<HTMLButtonElement>) => void;
     children?: React.ReactNode;
+    "aria-invalid"?: boolean;
+    "aria-describedby"?: string;
 }
 /**
- * DatePicker content props
+ * DatePicker body props (calendar dropdown content)
  */
-export interface DatePickerContentProps {
+export interface DatePickerBodyProps {
     isOpen?: boolean;
     className?: string;
     onClose?: () => void;
@@ -117,6 +132,13 @@ export interface DatePickerContentProps {
     placement?: DatePickerPlacement;
     offset?: number;
     presets?: DateRangePreset[];
+    /**
+     * Pin the popover 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 popover's base rung. */
+    lift?: boolean;
     children?: React.ReactNode;
 }
 /**
@@ -135,8 +157,8 @@ export interface DatePickerTheme {
     triggerFocusStates: Record<DatePickerState, string>;
     iconEndStyle: string;
     iconEndPadding: string;
-    contentStyle: string;
-    contentWithPresetsStyle: string;
+    bodyStyle: string;
+    bodyWithPresetsStyle: string;
     presetsContainerStyle: string;
     presetButtonStyle: string;
     helperTextStyle: string;

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

@@ -0,0 +1,7 @@
+import React from "react";
+import { DatePickerBodyProps } from "./DatePicker.types";
+/**
+ * DatePicker Body Component - contains the Calendar and optional Presets
+ * Uses portal positioning like Select component
+ */
+export declare const DatePickerBody: React.FC<DatePickerBodyProps>;