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

package/dist/components/forms/RichTextEditor/RichTextEditor.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useState, useCallback, useRef, useMemo, useEffect } from 'react';
 import { createPortal } from 'react-dom';
@@ -14,6 +15,7 @@ import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { PaintBrushIcon } from '@heroicons/react/24/solid';
 import { createDropdownAnimations } from '../Select/Select.animations.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
 const FONT_SIZE_OPTIONS = [
     { key: "xs", label: "XS", value: "0.75rem", px: 12, className: "text-xs" },
@@ -202,7 +204,11 @@ const DEFAULT_TOOLBAR = {
         "redo",
     ],
 };
-const RichTextEditor = React__default.forwardRef(({ size = "md", state = "default", className = "", label, labelClassName = "", helperText, helperTextClassName = "", value = "", onChange, placeholder = "Start typing...", id, required, minHeight = 120, maxHeight, toolbar: toolbarProp = DEFAULT_TOOLBAR, theme = {}, fontFamilies = DEFAULT_FONT_FAMILY_OPTIONS, loadFontsOnDemand = true, sanitize, ...props }, ref) => {
+const RichTextEditor = React__default.forwardRef(({ size = "md", state = "default", className = "", label, labelClassName = "", helperText, errorMessage, helperTextClassName = "", value = "", onChange, placeholder = "Start typing...", id, required, minHeight = 120, maxHeight, toolbar: toolbarProp = DEFAULT_TOOLBAR, theme = {}, fontFamilies = DEFAULT_FONT_FAMILY_OPTIONS, loadFontsOnDemand = true, sanitize, elevation, lift, ...props }, ref) => {
+    // Relative elevation: the floating toolbar (bubble menu) and the toolbar
+    // dropdowns lift above their host surface (overlay base = 5) so an editor
+    // inside a Popover/Modal still reads its floating chrome as a higher plane.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const [isFocused, setIsFocused] = useState(false);
     const [showToolbar, setShowToolbar] = useState(false);
     const [toolbarPosition, setToolbarPosition] = useState({ top: 0, left: 0 });
@@ -381,6 +387,10 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
     });
     const isDisabled = state === "disabled";
     const isInvalid = state === "invalid";
+    // errorMessage takes precedence over helperText while invalid; helperText
+    // behavior is unchanged otherwise.
+    const displayedMessage = isInvalid && errorMessage ? errorMessage : helperText;
+    const messageId = `${editorId}-message`;
     const getDataState = () => {
         if (isDisabled)
             return "disabled";
@@ -1465,17 +1475,17 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
                 const renderedDropdown = isClient
                     ? createPortal(jsx(AnimatePresence, { mode: "wait", children: showFontFamilyPicker && (jsx(motion.div, { ref: (el) => {
                                 fontFamilyPortalContentRef.current = el;
-                            }, role: "listbox", className: themeStyles.dropdownStyle, style: portalStyle, variants: shouldReduceMotion ? undefined : fontFamilyAnimations, initial: "initial", animate: fontFamilyPortalReady ? "visible" : "initial", exit: "exit", children: fontFamilies.map((option) => {
-                                const selected = option.key === formattingState.fontFamily;
-                                return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
-                                        event.preventDefault();
-                                        focusEditor();
-                                    }, onClick: (event) => {
-                                        event.preventDefault();
-                                        event.stopPropagation();
-                                        handleFontFamily(option.key);
-                                    }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "text-sm", style: { fontFamily: option.stack || undefined }, children: option.label }), option.family && (jsx("span", { className: "text-xs text-[var(--color-text-muted)]", children: "Google" }))] }) }, option.key));
-                            }) })) }), document.body)
+                            }, "data-flikkui-portal": "", role: "listbox", className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), themeStyles.dropdownStyle), style: portalStyle, variants: shouldReduceMotion ? undefined : fontFamilyAnimations, initial: "initial", animate: fontFamilyPortalReady ? "visible" : "initial", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: fontFamilies.map((option) => {
+                                    const selected = option.key === formattingState.fontFamily;
+                                    return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
+                                            event.preventDefault();
+                                            focusEditor();
+                                        }, onClick: (event) => {
+                                            event.preventDefault();
+                                            event.stopPropagation();
+                                            handleFontFamily(option.key);
+                                        }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "text-sm", style: { fontFamily: option.stack || undefined }, children: option.label }), option.family && (jsx("span", { className: "text-xs text-[var(--color-text-muted)]", children: "Google" }))] }) }, option.key));
+                                }) }) })) }), document.body)
                     : null;
                 return (jsxs("div", { className: "relative", "data-tool": "fontFamily", children: [jsx(Button, { ref: fontFamilyTriggerRef, size: "sm", color: "neutral", variant: "soft", className: cn(themeStyles.toolbarButtonStyle, "!justify-start !w-auto px-2 min-w-[4rem] gap-1"), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: (event) => {
                                 event.preventDefault();
@@ -1496,17 +1506,17 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
                 const renderedDropdown = isClient
                     ? createPortal(jsx(AnimatePresence, { mode: "wait", children: showFontWeightPicker && (jsx(motion.div, { ref: (el) => {
                                 fontWeightPortalContentRef.current = el;
-                            }, role: "listbox", className: themeStyles.dropdownStyle, style: portalStyle, variants: shouldReduceMotion ? undefined : fontWeightAnimations, initial: "initial", animate: fontWeightPortalReady ? "visible" : "initial", exit: "exit", children: FONT_WEIGHT_OPTIONS.map((option) => {
-                                const selected = option.key === formattingState.fontWeight;
-                                return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
-                                        event.preventDefault();
-                                        focusEditor();
-                                    }, onClick: (event) => {
-                                        event.preventDefault();
-                                        event.stopPropagation();
-                                        handleFontWeight(option.key);
-                                    }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "text-sm", style: { fontWeight: option.value }, children: option.label }), jsx("span", { className: "text-sm text-[var(--color-text-muted)]", children: option.value })] }) }, option.key));
-                            }) })) }), document.body)
+                            }, "data-flikkui-portal": "", role: "listbox", className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), themeStyles.dropdownStyle), style: portalStyle, variants: shouldReduceMotion ? undefined : fontWeightAnimations, initial: "initial", animate: fontWeightPortalReady ? "visible" : "initial", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: FONT_WEIGHT_OPTIONS.map((option) => {
+                                    const selected = option.key === formattingState.fontWeight;
+                                    return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
+                                            event.preventDefault();
+                                            focusEditor();
+                                        }, onClick: (event) => {
+                                            event.preventDefault();
+                                            event.stopPropagation();
+                                            handleFontWeight(option.key);
+                                        }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "text-sm", style: { fontWeight: option.value }, children: option.label }), jsx("span", { className: "text-sm text-[var(--color-text-muted)]", children: option.value })] }) }, option.key));
+                                }) }) })) }), document.body)
                     : null;
                 return (jsxs("div", { className: "relative", "data-tool": "fontWeight", children: [jsx(Button, { ref: fontWeightTriggerRef, size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: (event) => {
                                 event.preventDefault();
@@ -1527,17 +1537,17 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
                 const renderedDropdown = isClient
                     ? createPortal(jsx(AnimatePresence, { mode: "wait", children: showFontSizePicker && (jsx(motion.div, { ref: (el) => {
                                 fontSizePortalContentRef.current = el;
-                            }, role: "listbox", className: themeStyles.dropdownStyle, style: portalStyle, variants: shouldReduceMotion ? undefined : fontSizeAnimations, initial: "initial", animate: fontSizePortalReady ? "visible" : "initial", exit: "exit", children: FONT_SIZE_OPTIONS.map((option) => {
-                                const selected = option.key === formattingState.fontSize;
-                                return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
-                                        event.preventDefault();
-                                        focusEditor();
-                                    }, onClick: (event) => {
-                                        event.preventDefault();
-                                        event.stopPropagation();
-                                        handleFontSize(option.key);
-                                    }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "uppercase text-sm font-medium", children: option.label }), jsxs("span", { className: "text-sm text-[var(--color-text-muted)]", children: [option.px, "px"] })] }) }, option.key));
-                            }) })) }), document.body)
+                            }, "data-flikkui-portal": "", role: "listbox", className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), themeStyles.dropdownStyle), style: portalStyle, variants: shouldReduceMotion ? undefined : fontSizeAnimations, initial: "initial", animate: fontSizePortalReady ? "visible" : "initial", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: FONT_SIZE_OPTIONS.map((option) => {
+                                    const selected = option.key === formattingState.fontSize;
+                                    return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
+                                            event.preventDefault();
+                                            focusEditor();
+                                        }, onClick: (event) => {
+                                            event.preventDefault();
+                                            event.stopPropagation();
+                                            handleFontSize(option.key);
+                                        }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "uppercase text-sm font-medium", children: option.label }), jsxs("span", { className: "text-sm text-[var(--color-text-muted)]", children: [option.px, "px"] })] }) }, option.key));
+                                }) }) })) }), document.body)
                     : null;
                 return (jsxs("div", { className: "relative", "data-tool": "fontSize", children: [jsx(Button, { ref: fontSizeTriggerRef, size: "sm", color: "neutral", variant: "soft", className: cn(themeStyles.toolbarButtonStyle, "px-2 min-w-[3rem] gap-1"), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: (event) => {
                                 event.preventDefault();
@@ -1558,17 +1568,17 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
                 const renderedDropdown = isClient
                     ? createPortal(jsx(AnimatePresence, { mode: "wait", children: showLineHeightPicker && (jsx(motion.div, { ref: (el) => {
                                 lineHeightPortalContentRef.current = el;
-                            }, role: "listbox", className: themeStyles.dropdownStyle, style: portalStyle, variants: shouldReduceMotion ? undefined : lineHeightAnimations, initial: "initial", animate: lineHeightPortalReady ? "visible" : "initial", exit: "exit", children: LINE_HEIGHT_OPTIONS.map((option) => {
-                                const selected = option.key === formattingState.lineHeight;
-                                return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
-                                        event.preventDefault();
-                                        focusEditor();
-                                    }, onClick: (event) => {
-                                        event.preventDefault();
-                                        event.stopPropagation();
-                                        handleLineHeight(option.key);
-                                    }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "text-sm font-medium", children: option.label }), jsx("span", { className: "text-sm text-[var(--color-text-muted)]", children: option.value })] }) }, option.key));
-                            }) })) }), document.body)
+                            }, "data-flikkui-portal": "", role: "listbox", className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), themeStyles.dropdownStyle), style: portalStyle, variants: shouldReduceMotion ? undefined : lineHeightAnimations, initial: "initial", animate: lineHeightPortalReady ? "visible" : "initial", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: LINE_HEIGHT_OPTIONS.map((option) => {
+                                    const selected = option.key === formattingState.lineHeight;
+                                    return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
+                                            event.preventDefault();
+                                            focusEditor();
+                                        }, onClick: (event) => {
+                                            event.preventDefault();
+                                            event.stopPropagation();
+                                            handleLineHeight(option.key);
+                                        }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "text-sm font-medium", children: option.label }), jsx("span", { className: "text-sm text-[var(--color-text-muted)]", children: option.value })] }) }, option.key));
+                                }) }) })) }), document.body)
                     : null;
                 return (jsxs("div", { className: "relative", "data-tool": "lineHeight", children: [jsx(Button, { ref: lineHeightTriggerRef, size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: (event) => {
                                 event.preventDefault();
@@ -1589,17 +1599,17 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
                 const renderedDropdown = isClient
                     ? createPortal(jsx(AnimatePresence, { mode: "wait", children: showLetterSpacingPicker && (jsx(motion.div, { ref: (el) => {
                                 letterSpacingPortalContentRef.current = el;
-                            }, role: "listbox", className: themeStyles.dropdownStyle, style: portalStyle, variants: shouldReduceMotion ? undefined : letterSpacingAnimations, initial: "initial", animate: letterSpacingPortalReady ? "visible" : "initial", exit: "exit", children: LETTER_SPACING_OPTIONS.map((option) => {
-                                const selected = option.key === formattingState.letterSpacing;
-                                return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
-                                        event.preventDefault();
-                                        focusEditor();
-                                    }, onClick: (event) => {
-                                        event.preventDefault();
-                                        event.stopPropagation();
-                                        handleLetterSpacing(option.key);
-                                    }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "text-sm font-medium", children: option.label }), jsx("span", { className: "text-sm text-[var(--color-text-muted)]", children: option.value })] }) }, option.key));
-                            }) })) }), document.body)
+                            }, "data-flikkui-portal": "", role: "listbox", className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), themeStyles.dropdownStyle), style: portalStyle, variants: shouldReduceMotion ? undefined : letterSpacingAnimations, initial: "initial", animate: letterSpacingPortalReady ? "visible" : "initial", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: LETTER_SPACING_OPTIONS.map((option) => {
+                                    const selected = option.key === formattingState.letterSpacing;
+                                    return (jsx("button", { className: themeStyles.dropdownItemStyle, "data-active": selected ? "true" : "false", onMouseDown: (event) => {
+                                            event.preventDefault();
+                                            focusEditor();
+                                        }, onClick: (event) => {
+                                            event.preventDefault();
+                                            event.stopPropagation();
+                                            handleLetterSpacing(option.key);
+                                        }, role: "option", "aria-selected": selected, children: jsxs("span", { className: "flex items-center justify-between gap-3", children: [jsx("span", { className: "text-sm font-medium", children: option.label }), jsx("span", { className: "text-sm text-[var(--color-text-muted)]", children: option.value })] }) }, option.key));
+                                }) }) })) }), document.body)
                     : null;
                 return (jsxs("div", { className: "relative", "data-tool": "letterSpacing", children: [jsx(Button, { ref: letterSpacingTriggerRef, size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: (event) => {
                                 event.preventDefault();
@@ -1634,7 +1644,7 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
                 const renderedColorDropdown = isClient
                     ? createPortal(jsx(AnimatePresence, { mode: "wait", children: showColorPicker && (jsx(motion.div, { ref: (el) => {
                                 colorPortalContentRef.current = el;
-                            }, className: cn(themeStyles.dropdownStyle, "!max-h-none !overflow-visible"), style: portalStyle, variants: shouldReduceMotion ? undefined : colorAnimations, initial: "initial", animate: colorPortalReady ? "visible" : "initial", exit: "exit", children: jsx(ScrollArea, { type: "none", className: "max-h-[20rem]", children: jsxs("div", { className: themeStyles.colorPickerStyle, children: [recentColors.length > 0 && (jsxs("div", { className: "flex flex-col gap-1 pb-2 mb-1 border-b border-[var(--color-border)]", children: [jsx("span", { className: "text-[11px] font-medium uppercase tracking-wide text-[var(--color-text-muted)]", children: "Recent" }), jsx("div", { className: "flex gap-0.5", children: recentColors.map((token) => renderSwatch(resolveTailwindColor(token), token, `recent ${token}`)) })] })), jsxs("div", { className: "flex flex-col gap-1", children: [jsx("span", { className: "text-[11px] font-medium uppercase tracking-wide text-[var(--color-text-muted)]", children: "Mono" }), jsx("div", { className: "flex gap-0.5", children: MONO_COLORS.map((color) => renderSwatch(color.value, color.token, color.name)) }), jsx("span", { className: "mt-2 text-[11px] font-medium uppercase tracking-wide text-[var(--color-text-muted)]", children: "Spectrum" }), TAILWIND_COLOR_FAMILIES.map((family) => (jsx("div", { className: "flex gap-0.5", children: getTailwindShadeTokens(family).map((token) => renderSwatch(resolveTailwindColor(token), token, token)) }, family)))] })] }) }) })) }), document.body)
+                            }, "data-flikkui-portal": "", className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), themeStyles.dropdownStyle, "!max-h-none !overflow-visible"), style: portalStyle, variants: shouldReduceMotion ? undefined : colorAnimations, initial: "initial", animate: colorPortalReady ? "visible" : "initial", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: jsx(ScrollArea, { type: "none", className: "max-h-[20rem]", children: jsxs("div", { className: themeStyles.colorPickerStyle, children: [recentColors.length > 0 && (jsxs("div", { className: "flex flex-col gap-1 pb-2 mb-1 border-b border-[var(--color-border)]", children: [jsx("span", { className: "text-[11px] font-medium uppercase tracking-wide text-[var(--color-text-muted)]", children: "Recent" }), jsx("div", { className: "flex gap-0.5", children: recentColors.map((token) => renderSwatch(resolveTailwindColor(token), token, `recent ${token}`)) })] })), jsxs("div", { className: "flex flex-col gap-1", children: [jsx("span", { className: "text-[11px] font-medium uppercase tracking-wide text-[var(--color-text-muted)]", children: "Mono" }), jsx("div", { className: "flex gap-0.5", children: MONO_COLORS.map((color) => renderSwatch(color.value, color.token, color.name)) }), jsx("span", { className: "mt-2 text-[11px] font-medium uppercase tracking-wide text-[var(--color-text-muted)]", children: "Spectrum" }), TAILWIND_COLOR_FAMILIES.map((family) => (jsx("div", { className: "flex gap-0.5", children: getTailwindShadeTokens(family).map((token) => renderSwatch(resolveTailwindColor(token), token, token)) }, family)))] })] }) }) }) })) }), document.body)
                     : null;
                 return (jsxs("div", { className: "relative", "data-tool": "textColor", children: [jsx(Button, { ref: colorTriggerRef, size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), onMouseDown: handleMouseDown, onClick: (event) => {
                                 event.preventDefault();
@@ -1674,9 +1684,9 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
     const renderToolbar = () => {
         if (!toolbarConfig.show || !toolbarConfig.tools)
             return null;
-        const tools = toolbarConfig.tools.map((tool) => renderToolbarTool(tool, tool));
+        const tools = toolbarConfig.tools.map((tool, index) => renderToolbarTool(tool, `${tool}-${index}`));
         if (toolbarConfig.position === "floating") {
-            return (jsx(AnimatePresence, { mode: "wait", children: showToolbar && (jsx(motion.div, { ref: toolbarRef, variants: shouldReduceMotion ? undefined : floatingToolbarVariants, initial: "initial", animate: "animate", exit: "exit", className: cn(themeStyles.floatingToolbarStyle, toolbarConfig.className), style: { position: "absolute", top: toolbarPosition.top, left: toolbarPosition.left, zIndex: 50 }, children: tools }, "floating-toolbar")) }));
+            return (jsx(AnimatePresence, { mode: "wait", children: showToolbar && (jsx(motion.div, { ref: toolbarRef, variants: shouldReduceMotion ? undefined : floatingToolbarVariants, initial: "initial", animate: "animate", exit: "exit", className: cn(surfaceClasses(surfaceLevel, { translucent: true }), themeStyles.floatingToolbarStyle, toolbarConfig.className), style: { position: "absolute", top: toolbarPosition.top, left: toolbarPosition.left, zIndex: 50 }, children: jsx(SurfaceProvider, { level: surfaceLevel, children: tools }) }, "floating-toolbar")) }));
         }
         return (jsx("div", { ref: toolbarRef, className: cn(themeStyles.toolbarStyle, toolbarConfig.className), children: tools }));
     };
@@ -1699,7 +1709,7 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
                                         setShowToolbar(false);
                                     }
                                     closeAllPickers();
-                                }, "aria-invalid": isInvalid, "aria-required": required, role: "textbox", "aria-multiline": "true", "aria-label": typeof label === 'string' ? label : "Rich text editor", suppressContentEditableWarning: true })] }), toolbarConfig.position === "floating" && renderToolbar()] }), helperText && (typeof helperText === 'string' ? (jsx("div", { className: cn(themeStyles.helperText, helperTextClassName), children: helperText })) : (helperText))] }));
+                                }, "aria-invalid": isInvalid, "aria-required": required, "aria-describedby": displayedMessage ? messageId : undefined, role: "textbox", "aria-multiline": "true", "aria-label": typeof label === 'string' ? label : "Rich text editor", suppressContentEditableWarning: true })] }), toolbarConfig.position === "floating" && renderToolbar()] }), displayedMessage && (typeof displayedMessage === 'string' ? (jsx("div", { id: messageId, role: isInvalid ? "alert" : undefined, className: cn(themeStyles.helperText, helperTextClassName), children: displayedMessage })) : (displayedMessage))] }));
 });
 RichTextEditor.displayName = "RichTextEditor";
 

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

@@ -1,3 +1,4 @@
+"use client";
 import { formsBaseTheme } from '../forms.theme.js';
 
 /**
@@ -99,12 +100,12 @@ const richTextEditorTheme = {
     // 1px bleed past the parent's `overflow-hidden` clip in Safari/Chromium.
     toolbarStyle: "flex items-center m-0.5 gap-0.5 p-0.5 rounded-[var(--form-radius)] dark:bg-[var(--color-surface)]/0",
     // Toolbar styling (floating variant — selection-anchored)
-    floatingToolbarStyle: "flex items-center gap-1 p-1 rounded-xl border border-[var(--color-border)] bg-[var(--color-surface-overlay)]/80 backdrop-blur-md shadow-real-xl overflow-hidden",
+    floatingToolbarStyle: "flex items-center gap-1 p-1 rounded-xl border border-[var(--color-border)] backdrop-blur-md overflow-hidden",
     // Toolbar button — single source of truth via data-[state=active]
     // (aria-pressed remains as proper ARIA on toggle buttons, but styling is decoupled)
     toolbarButtonStyle: "inline-flex items-center justify-center rounded-[calc(var(--radius-base)*0.85)] border border-transparent bg-transparent text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors duration-300 disabled:opacity-50 disabled:cursor-not-allowed data-[state=active]:bg-[var(--color-background-secondary)] data-[state=active]:text-[var(--color-text-primary)] data-[state=active]:border-[var(--color-border)] data-[state=active]:shadow-inner",
     // Dropdown surface (visual only — positioning handled at use site via portal)
-    dropdownStyle: "min-w-[120px] max-h-[18rem] overflow-y-auto py-1 bg-[var(--color-surface-overlay)]/80 backdrop-blur-md rounded-[var(--form-radius)] shadow-xl ring-1 ring-[var(--color-border)] focus:outline-none",
+    dropdownStyle: "min-w-[120px] max-h-[18rem] overflow-y-auto py-1 backdrop-blur-md rounded-[var(--form-radius)] shadow-xl ring-1 ring-[var(--color-border)] focus:outline-none",
     // Dropdown item — uses data-[active=true] for selected state
     dropdownItemStyle: "block w-full px-3 py-2 text-left text-sm text-[var(--color-text-primary)] hover:bg-[var(--color-surface-hover)] transition-colors duration-150 disabled:opacity-50 disabled:cursor-not-allowed data-[active=true]:bg-[var(--color-primary-50)] data-[active=true]:text-[var(--color-primary-900)] data-[active=true]:dark:bg-[var(--color-primary-400)]/10 data-[active=true]:dark:text-[var(--color-primary-400)]",
     // Separator between toolbar sections

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

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { SurfaceElevation } from '../../../theme/SurfaceContext';
 /**
  * Rich Text Editor component props
  * @property {RichTextEditorSize} size - The size of the editor
@@ -22,6 +23,12 @@ export interface RichTextEditorProps extends Omit<React.HTMLAttributes<HTMLDivEl
     label?: React.ReactNode;
     /** Optional helper text displayed below the editor */
     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;
     /** The HTML content value */
     value?: string;
     /** Callback when content changes */
@@ -72,6 +79,13 @@ export interface RichTextEditorProps extends Omit<React.HTMLAttributes<HTMLDivEl
      * <RichTextEditor sanitize={DOMPurify.sanitize} />
      */
     sanitize?: (html: string) => string;
+    /**
+     * Pin the floating toolbar / dropdown surface elevation rung (overrides the
+     * automatic relative lift) — a rung number (1–8) or a semantic alias.
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the floating surface's base rung. */
+    lift?: boolean;
 }
 export type RichTextEditorSize = 'sm' | 'md' | 'lg';
 export type RichTextEditorState = 'default' | 'disabled' | 'invalid';

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

@@ -1,32 +1,24 @@
+"use client";
+import '../../../theme/ThemeContext.js';
+import '../../../theme/SurfaceContext.js';
+import { getOverlayMenuVariants } from '../../../theme/animations.js';
+
 /**
  * Creates direction-aware dropdown animation variants for the Select component
  * @param isFlipped - Whether the dropdown is positioned above (flipped) or below the trigger
  * @returns Animation variants that match the positioning direction
  */
-const createDropdownAnimations = (isFlipped) => ({
-    initial: {
-        opacity: 0,
-        y: isFlipped ? 10 : -10, // Animate from opposite direction when flipped
-        scale: 0.95,
-    },
-    visible: {
-        opacity: 1,
-        y: 0,
-        scale: 1,
-        transition: {
-            duration: 0.2,
-            ease: 'easeOut'
-        }
-    },
-    exit: {
-        opacity: 0,
-        y: isFlipped ? 10 : -10, // Exit in same direction as entry
-        scale: 0.95,
-        transition: {
-            duration: 0.15,
-            ease: 'easeIn'
-        }
-    }
-});
+const createDropdownAnimations = (isFlipped) => {
+    const side = isFlipped ? 'top' : 'bottom';
+    return getOverlayMenuVariants(side, {
+        scale: 0.97,
+        shift: 6,
+    });
+};
+/**
+ * Default dropdown animation variants for backward compatibility
+ * @deprecated Use createDropdownAnimations() for better UX with direction awareness
+ */
+createDropdownAnimations(false);
 
 export { createDropdownAnimations };

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

@@ -81,6 +81,8 @@ export interface SelectOptionsExtendedProps extends SelectOptionsProps {
     triggerRef?: React.RefObject<HTMLElement>;
     /** id applied to the listbox element for aria-controls matching */
     listboxId?: string;
+    /** id of the element that labels the listbox (e.g. the field's FormLabel) */
+    "aria-labelledby"?: string;
 }
 /**
  * Select Options Component
@@ -89,7 +91,7 @@ export declare const SelectOptions: React.FC<SelectOptionsExtendedProps>;
 /**
  * Select Option Component
  */
-export declare const SelectOption: <T extends any>({ value, isSelected, disabled, className, onSelect, children, }: SelectOptionProps<T>) => import("react/jsx-runtime").JSX.Element;
+export declare const SelectOption: <T extends any>({ value, isSelected, disabled, className, onSelect, children, }: SelectOptionProps<T>) => import("react/jsx-runtime").JSX.Element | null;
 export declare const Select: <T = unknown>(props: SelectProps<T> & React.RefAttributes<HTMLDivElement>) => React.ReactElement | null;
 export { useSelectState };
 export type { UseSelectStateProps, UseSelectStateReturn };

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,13 +8,14 @@ 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, PlusIcon, CheckIcon, MagnifyingGlassIcon } from '@heroicons/react/24/outline';
+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 { 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';
 
 /**
@@ -73,7 +75,7 @@ function SelectProvider({ children, selectState, size = "md", componentState = "
 /**
  * Select Button Component
  */
-const SelectButton = ({ id, disabled, isOpen, state = "default", size = "md", iconStart, iconEnd, contentStart, contentEnd, className = "", onClick, onFocus, onBlur, children, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedby, "aria-labelledby": ariaLabelledby, }) => {
+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 || "";
@@ -98,13 +100,16 @@ const SelectButton = ({ id, disabled, isOpen, state = "default", size = "md", ic
         ? focusStateStyle ||
             "shadow-[inset_0_0_0_1px_var(--color-primary)] ring-4 ring-[var(--color-primary)]/10"
         : "";
-    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, 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 }))] }));
+    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, listboxId, }) => {
+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
@@ -125,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
@@ -265,7 +270,7 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
         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, id: listboxId, 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
@@ -278,13 +283,13 @@ 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...", "aria-label": "Search options", 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", { "data-flikkui-portal": "", className: isDarkMode ? "dark" : undefined, children: optionsContent }), document.body);
@@ -299,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 || "";
@@ -307,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 = () => {
@@ -322,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
@@ -351,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, 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, 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]);
@@ -367,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
@@ -393,6 +408,18 @@ 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 || "";
@@ -403,11 +430,15 @@ const SelectInner = ({ id, name, size = "md", state = "default", value, displayV
     // 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 && (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, className: className, "aria-labelledby": label && typeof label === 'string' ? `${selectId}-label` : undefined, "aria-invalid": state === "invalid" || undefined, "aria-describedby": helperText ? `${selectId}-helper` : undefined, 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, listboxId: `${selectId}-listbox`, children: children ||
+                            : 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)
@@ -417,7 +448,10 @@ const SelectInner = ({ id, name, size = "md", state = "default", value, displayV
                                         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));
+                                        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) : "" }))] }) }));
 };

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

@@ -11,8 +11,8 @@ const selectTheme = {
     baseStyle: formsBaseTheme.inputGroupBaseStyle + " items-center justify-between",
     // Button wrapper style
     buttonWrapperStyle: "relative w-full",
-    // Button style - surface flips automatically between light/dark
-    buttonStyle: "w-full cursor-pointer bg-[var(--color-surface)]",
+    // 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