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

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

@@ -13,7 +13,11 @@ import { InputProps, InputTheme } from '../Input/Input.types';
 export interface InputCreditCardProps {
     /** Visual/validation state of the entire card group */
     state?: 'default' | 'disabled' | 'invalid';
-    /** Consolidated error message shown below all fields */
+    /** Consolidated error message shown below all fields when `state="invalid"` */
+    errorMessage?: React.ReactNode;
+    /**
+     * @deprecated Use `errorMessage` instead. Kept as an alias for backward compatibility.
+     */
     error?: React.ReactNode;
     /** Callback when card number changes */
     onCardNumberChange?: (cardNumber: string) => void;

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

@@ -2,3 +2,4 @@ export { InputCreditCard } from './InputCreditCard';
 export type { InputCreditCardProps, InputCreditCardThemeOverrides } from './InputCreditCard.types';
 export { inputCreditCardTheme, styledInputCreditCardTheme } from './InputCreditCard.theme';
 export { containerVariants, inputVariants } from './InputCreditCard.animations';
+export { isValidExpiryDate } from '../Input/inputMasks';

package/dist/components/forms/InputDate/InputDate.js

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

package/dist/components/forms/InputOTP/InputOTP.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
-import React__default, { useRef, useState, useEffect, useCallback } from 'react';
+import React__default, { useRef, useState, useCallback, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { Input } from '../Input/Input.js';
 import '../Input/Input.theme.js';
@@ -21,7 +22,7 @@ import { inputOTPTheme } from './InputOTP.theme.js';
  * />
  * ```
  */
-const InputOTP = React__default.forwardRef(({ length = 6, value, defaultValue, onChange, onComplete, state = 'default', disabled = false, label, helperText, error, autoFocus = true, className, id: idProp, ...props }, ref) => {
+const InputOTP = React__default.forwardRef(({ length = 6, value, defaultValue, onChange, onComplete, state = 'default', disabled = false, label, helperText, errorMessage, error, autoFocus = true, className, id: idProp, ...props }, ref) => {
     const inputRefs = useRef([]);
     const theme = inputOTPTheme;
     const generatedId = React__default.useId();
@@ -32,8 +33,13 @@ const InputOTP = React__default.forwardRef(({ length = 6, value, defaultValue, o
     // Internal state for uncontrolled usage — seeded with defaultValue
     const [internalValue, setInternalValue] = useState(defaultValue !== null && defaultValue !== void 0 ? defaultValue : '');
     // Use controlled value if provided, otherwise use internal state
-    const currentValue = value !== undefined ? value : internalValue;
-    const setValue = onChange || setInternalValue;
+    const isControlled = value !== undefined;
+    const currentValue = isControlled ? value : internalValue;
+    const setValue = useCallback((next) => {
+        if (!isControlled)
+            setInternalValue(next);
+        onChange === null || onChange === void 0 ? void 0 : onChange(next);
+    }, [isControlled, onChange]);
     // Convert value to array of characters
     const valueArray = currentValue.padEnd(length, '').split('').slice(0, length);
     // Auto-focus first input on mount
@@ -138,8 +144,14 @@ const InputOTP = React__default.forwardRef(({ length = 6, value, defaultValue, o
             : "state-default";
     // Resolved label state for FormLabel
     const labelState = isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default';
-    // Resolved helper text to display — prefer helperText, fall back to error
-    const displayedHelperText = helperText !== null && helperText !== void 0 ? helperText : error;
+    // Per-slot accessible name. Slot 0 stays linked to the visible <FormLabel>
+    // via htmlFor (no aria-label — an aria-label would override that
+    // association). Slots 2+ previously had no accessible name of their own;
+    // give each an indexed name so every slot is announced distinctly.
+    const getSlotAriaLabel = (index) => index === 0 ? undefined : `Digit ${index + 1} of ${length}`;
+    // Resolved message to display: errorMessage takes precedence while
+    // invalid, then helperText, then the deprecated `error` string.
+    const displayedHelperText = isInvalid && errorMessage ? errorMessage : (helperText !== null && helperText !== void 0 ? helperText : error);
     // Build classes with shadcn pattern - user className has highest priority
     const wrapperClasses = cn(theme.wrapperStyle, stateClass, className);
     const containerClasses = cn(theme.containerStyle);
@@ -168,16 +180,16 @@ const InputOTP = React__default.forwardRef(({ length = 6, value, defaultValue, o
                 // For 6-digit OTP, create two groups of 3
                 jsxs(Fragment, { children: [jsx("div", { className: "flex", children: Array.from({ length: 3 }, (_, i) => (jsx(Input, { ref: (el) => {
                                     inputRefs.current[i] = el;
-                                }, id: `otp-input-${i}`, type: "text", value: valueArray[i] || '', onChange: (e) => handleChange(i, e.target.value), onKeyDown: (e) => handleKeyDown(i, e), onFocus: () => handleFocus(i), onBlur: handleBlur, onPaste: i === 0 ? handlePaste : undefined, disabled: isDisabled, state: isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default', "aria-describedby": displayedHelperText ? helperTextId : undefined, maxLength: 1, className: theme.inputStyle, inputGroupClassName: getInputClasses(i), wrapperClassName: "space-y-0 w-auto" }, i))) }), jsx("span", { className: theme.separatorStyle, children: "\u2014" }), jsx("div", { className: "flex", children: Array.from({ length: 3 }, (_, i) => {
+                                }, id: `otp-input-${i}`, type: "text", value: valueArray[i] || '', onChange: (e) => handleChange(i, e.target.value), onKeyDown: (e) => handleKeyDown(i, e), onFocus: () => handleFocus(i), onBlur: handleBlur, onPaste: i === 0 ? handlePaste : undefined, disabled: isDisabled, state: isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default', "aria-label": getSlotAriaLabel(i), "aria-describedby": displayedHelperText ? helperTextId : undefined, maxLength: 1, className: theme.inputStyle, inputGroupClassName: getInputClasses(i), wrapperClassName: "space-y-0 w-auto" }, i))) }), jsx("span", { className: theme.separatorStyle, children: "\u2014" }), jsx("div", { className: "flex", children: Array.from({ length: 3 }, (_, i) => {
                                 const index = i + 3;
                                 return (jsx(Input, { ref: (el) => {
                                         inputRefs.current[index] = el;
-                                    }, id: `otp-input-${index}`, type: "text", value: valueArray[index] || '', onChange: (e) => handleChange(index, e.target.value), onKeyDown: (e) => handleKeyDown(index, e), onFocus: () => handleFocus(index), onBlur: handleBlur, disabled: isDisabled, state: isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default', "aria-describedby": displayedHelperText ? helperTextId : undefined, maxLength: 1, className: theme.inputStyle, inputGroupClassName: getInputClasses(index), wrapperClassName: "space-y-0 w-auto" }, index));
+                                    }, id: `otp-input-${index}`, type: "text", value: valueArray[index] || '', onChange: (e) => handleChange(index, e.target.value), onKeyDown: (e) => handleKeyDown(index, e), onFocus: () => handleFocus(index), onBlur: handleBlur, disabled: isDisabled, state: isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default', "aria-label": getSlotAriaLabel(index), "aria-describedby": displayedHelperText ? helperTextId : undefined, maxLength: 1, className: theme.inputStyle, inputGroupClassName: getInputClasses(index), wrapperClassName: "space-y-0 w-auto" }, index));
                             }) })] })) : (
                 // For other lengths, create one group
                 jsx("div", { className: "flex", children: Array.from({ length }, (_, index) => (jsx(Input, { ref: (el) => {
                             inputRefs.current[index] = el;
-                        }, id: `otp-input-${index}`, type: "text", value: valueArray[index] || '', onChange: (e) => handleChange(index, e.target.value), onKeyDown: (e) => handleKeyDown(index, e), onFocus: () => handleFocus(index), onBlur: handleBlur, onPaste: index === 0 ? handlePaste : undefined, disabled: isDisabled, state: isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default', "aria-describedby": displayedHelperText ? helperTextId : undefined, maxLength: 1, className: theme.inputStyle, inputGroupClassName: getInputClasses(index), wrapperClassName: "space-y-0 w-auto" }, index))) })) }), displayedHelperText && (jsx("div", { id: helperTextId, className: cn(theme.helperText), children: displayedHelperText }))] }));
+                        }, id: `otp-input-${index}`, type: "text", value: valueArray[index] || '', onChange: (e) => handleChange(index, e.target.value), onKeyDown: (e) => handleKeyDown(index, e), onFocus: () => handleFocus(index), onBlur: handleBlur, onPaste: index === 0 ? handlePaste : undefined, disabled: isDisabled, state: isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default', "aria-label": getSlotAriaLabel(index), "aria-describedby": displayedHelperText ? helperTextId : undefined, maxLength: 1, className: theme.inputStyle, inputGroupClassName: getInputClasses(index), wrapperClassName: "space-y-0 w-auto" }, index))) })) }), displayedHelperText && (jsx("div", { id: helperTextId, className: cn(theme.helperText), children: displayedHelperText }))] }));
 });
 InputOTP.displayName = 'InputOTP';
 

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

@@ -45,9 +45,15 @@ export interface InputOTPProps extends Omit<React.HTMLAttributes<HTMLDivElement>
      * Helper text below the inputs
      */
     helperText?: React.ReactNode;
+    /**
+     * Error message shown instead of `helperText` when `state="invalid"`.
+     * Takes precedence over both `helperText` and the deprecated `error` string
+     * while invalid; `helperText`/`error` are unaffected otherwise.
+     */
+    errorMessage?: React.ReactNode;
     /**
      * Error message
-     * @deprecated Use `state='invalid'` with `helperText` instead.
+     * @deprecated Use `state='invalid'` with `errorMessage` instead.
      */
     error?: string;
     /**

package/dist/components/forms/InputTag/InputTag.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import React__default, { useMemo, useState, useRef, useEffect, useCallback } from 'react';
 import { AnimatePresence, motion } from 'motion/react';
@@ -12,6 +13,7 @@ import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { createDropdownAnimations } from '../Select/Select.animations.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
 import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
 /**
  * Default filter function for suggestions
@@ -19,8 +21,11 @@ import { useDarkMode } from '../../../hooks/useDarkMode.js';
 const defaultFilterFn = (option, inputValue) => {
     return option.label.toLowerCase().includes(inputValue.toLowerCase());
 };
-const InputTagOptions = ({ isOpen, onClose, triggerRef, filteredOptions, selectedTags, highlightedIndex, setHighlightedIndex, onSelectOption, showSelectedIndicator, portal, placement, offset, emptyMessage, className, theme, }) => {
+const InputTagOptions = ({ isOpen, onClose, triggerRef, filteredOptions, selectedTags, highlightedIndex, setHighlightedIndex, onSelectOption, showSelectedIndicator, portal, placement, offset, emptyMessage, className, theme, elevation, lift, listboxId, }) => {
     var _a;
+    // Relative elevation: the suggestion dropdown lifts above its host surface
+    // (overlay base = 5) so an InputTag inside a Popover/Modal still reads higher.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const optionsRef = useRef(null);
     const isDarkMode = useDarkMode();
     const isClient = useIsClient();
@@ -60,7 +65,7 @@ const InputTagOptions = ({ isOpen, onClose, triggerRef, filteredOptions, selecte
         document.addEventListener("mousedown", handleClickOutside);
         return () => document.removeEventListener("mousedown", handleClickOutside);
     }, [isOpen, onClose, portal, contentRef, optionsRef, triggerRef]);
-    const optionsContent = (jsx(AnimatePresence, { mode: "wait", children: isOpen && (jsx(motion.div, { ref: combinedRef, role: "listbox", className: cn(theme.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 }), theme.dropdownStyle, className), style: {
                 ...cssVariables,
                 overscrollBehavior: "contain",
                 ...(portal
@@ -70,18 +75,18 @@ const InputTagOptions = ({ isOpen, onClose, triggerRef, filteredOptions, selecte
                         width: `${position.width}px`,
                     }
                     : {}),
-            }, tabIndex: -1, variants: animations, initial: "initial", animate: "visible", exit: "exit", children: filteredOptions.length === 0 ? (jsx("div", { className: theme.emptyMessageStyle, children: emptyMessage })) : (jsxs(Fragment, { children: [(filteredOptions.length > 100 ? filteredOptions.slice(0, 100) : filteredOptions).map((option, index) => {
-                        const isSelected = selectedTags.includes(option.value);
-                        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(theme.optionStyle, isHighlighted && theme.highlightedOptionStyle, option.disabled && theme.disabledOptionStyle, isCreateOption && theme.createOptionStyle), onMouseEnter: () => !option.disabled && setHighlightedIndex(index), onClick: () => {
-                                if (!option.disabled) {
-                                    onSelectOption(option, isCreateOption);
-                                }
-                            }, 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 })] })) : (jsxs("span", { className: "flex items-center justify-between gap-2", children: [jsx("span", { className: "block truncate", children: option.label }), showSelectedIndicator && isSelected && (jsx(CheckIcon, { className: "size-4 shrink-0 text-[var(--color-primary)]", 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"] }))] })) })) }));
+            }, tabIndex: -1, variants: animations, initial: "initial", animate: "visible", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: filteredOptions.length === 0 ? (jsx("div", { className: theme.emptyMessageStyle, children: emptyMessage })) : (jsxs(Fragment, { children: [(filteredOptions.length > 100 ? filteredOptions.slice(0, 100) : filteredOptions).map((option, index) => {
+                            const isSelected = selectedTags.includes(option.value);
+                            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(theme.optionStyle, isHighlighted && theme.highlightedOptionStyle, option.disabled && theme.disabledOptionStyle, isCreateOption && theme.createOptionStyle), onMouseEnter: () => !option.disabled && setHighlightedIndex(index), onClick: () => {
+                                    if (!option.disabled) {
+                                        onSelectOption(option, isCreateOption);
+                                    }
+                                }, 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 })] })) : (jsxs("span", { className: "flex items-center justify-between gap-2", children: [jsx("span", { className: "block truncate", children: option.label }), showSelectedIndicator && isSelected && (jsx(CheckIcon, { className: "size-4 shrink-0 text-[var(--color-primary)]", 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;
 };
@@ -127,7 +132,7 @@ const InputTagOptions = ({ isOpen, onClose, triggerRef, filteredOptions, selecte
  */
 const InputTag = React__default.forwardRef(({ value, defaultValue = [], onChange, maxTags, allowDuplicates = false, size = "md", state = "default", label, helperText, placeholder = "Add a tag...", disabled = false, className, inputClassName, tagsContainerClassName, tagClassName, theme: customTheme, 
 // Dropdown props
-suggestions, creatable = true, openOnFocus = true, filterFn = defaultFilterFn, emptyMessage = "No suggestions", createLabel, hideSelected = true, showSelectedIndicator = false, portal = true, placement = "bottom-start", offset = 8, dropdownClassName, ...props }, ref) => {
+suggestions, creatable = true, openOnFocus = true, filterFn = defaultFilterFn, emptyMessage = "No suggestions", createLabel, hideSelected = true, showSelectedIndicator = false, portal = true, placement = "bottom-start", offset = 8, dropdownClassName, elevation, lift, ...props }, ref) => {
     // Merge default theme with custom theme overrides
     const theme = useMemo(() => ({
         ...inputTagTheme,
@@ -135,6 +140,10 @@ suggestions, creatable = true, openOnFocus = true, filterFn = defaultFilterFn, e
     }), [customTheme]);
     // Determine if dropdown mode is enabled
     const hasDropdown = suggestions !== undefined && suggestions.length > 0;
+    // id for the suggestions listbox — wired to the trigger's aria-controls
+    // (role="combobox" requires it per ARIA's required-attributes rule).
+    const generatedListboxId = React__default.useId();
+    const listboxId = `${generatedListboxId}-listbox`;
     // Internal state for tags (controlled/uncontrolled pattern)
     const [internalTags, setInternalTags] = useState(defaultValue || []);
     const [inputValue, setInputValue] = useState("");
@@ -144,6 +153,9 @@ suggestions, creatable = true, openOnFocus = true, filterFn = defaultFilterFn, e
     const inputRef = useRef(null);
     const wrapperRef = useRef(null);
     const warningTimeoutRef = useRef(null);
+    // Guards against the dropdown reopening when handleSelectOption refocuses
+    // the input after a click-selection (mirrors Combobox's justSelectedRef).
+    const justSelectedRef = useRef(false);
     // Determine if component is controlled
     const isControlled = value !== undefined;
     const tags = isControlled ? value : internalTags;
@@ -317,6 +329,9 @@ suggestions, creatable = true, openOnFocus = true, filterFn = defaultFilterFn, e
             setInputValue("");
             setIsOpen(false);
             setHighlightedIndex(-1);
+            // Prevent the imminent refocus below from immediately reopening the
+            // dropdown via handleFocus's openOnFocus check.
+            justSelectedRef.current = true;
             (_a = inputRef.current) === null || _a === void 0 ? void 0 : _a.focus();
         }
     }, [addTag]);
@@ -390,22 +405,51 @@ suggestions, creatable = true, openOnFocus = true, filterFn = defaultFilterFn, e
         tags.length,
         removeTag,
     ]);
-    // Handle paste
+    // Handle paste — parse every comma-separated value and commit them all in
+    // ONE state update. addTag() closes over the `tags` in scope at the time
+    // it's called, so calling it in a loop/forEach means every call after the
+    // first still sees the pre-paste array and each commit overwrites the
+    // previous one (only the last tag would survive). Building the full valid
+    // list up front and calling updateTags() once avoids that stale closure.
     const handlePaste = useCallback((e) => {
         e.preventDefault();
         const pastedText = e.clipboardData.getData("text");
-        // Split by comma and add each tag
         const pastedTags = pastedText
             .split(",")
             .map((t) => t.trim())
             .filter(Boolean);
-        if (pastedTags.length > 0) {
-            pastedTags.forEach((tag) => addTag(tag));
-            setInputValue("");
+        if (pastedTags.length === 0)
+            return;
+        const validTags = [];
+        const duplicateTags = [];
+        for (const tag of pastedTags) {
+            // Respect maxTags across the whole batch, not just the existing tags.
+            if (maxTags && tags.length + validTags.length >= maxTags)
+                break;
+            if (!allowDuplicates &&
+                (tags.includes(tag) || validTags.includes(tag))) {
+                if (!duplicateTags.includes(tag)) {
+                    duplicateTags.push(tag);
+                }
+                continue;
+            }
+            validTags.push(tag);
         }
-    }, [addTag]);
+        if (duplicateTags.length > 0) {
+            showDuplicateWarning(duplicateTags[0]);
+        }
+        if (validTags.length > 0) {
+            updateTags([...tags, ...validTags]);
+        }
+        setInputValue("");
+    }, [tags, maxTags, allowDuplicates, updateTags, showDuplicateWarning]);
     // Handle focus
     const handleFocus = useCallback(() => {
+        // Skip reopening if we just selected an option and are being refocused.
+        if (justSelectedRef.current) {
+            justSelectedRef.current = false;
+            return;
+        }
         if (hasDropdown && openOnFocus && !disabled) {
             setIsOpen(true);
         }
@@ -453,7 +497,7 @@ suggestions, creatable = true, openOnFocus = true, filterFn = defaultFilterFn, e
                             : placeholder, size: size, state: state, label: label, 
                         // Only pass helperText to Input when NOT in dropdown mode
                         // Otherwise the dropdown positions below the helper text
-                        helperText: hasDropdown ? undefined : displayHelperText, disabled: isInputDisabled, className: inputClassName, "aria-expanded": hasDropdown ? isOpen : undefined, "aria-haspopup": hasDropdown ? "listbox" : undefined, "aria-autocomplete": hasDropdown ? "list" : undefined }), hasDropdown && (jsx(InputTagOptions, { isOpen: isOpen, onClose: handleCloseDropdown, triggerRef: wrapperRef, filteredOptions: filteredOptions, selectedTags: tags, highlightedIndex: highlightedIndex, setHighlightedIndex: setHighlightedIndex, onSelectOption: handleSelectOption, showSelectedIndicator: showSelectedIndicator, portal: portal, placement: placement, offset: offset, emptyMessage: emptyMessage, className: dropdownClassName, theme: theme }))] }), hasDropdown && displayHelperText && (jsx("p", { className: "text-sm text-[var(--color-text-muted)] mt-1.5", children: displayHelperText })), jsx("div", { className: cn(theme.tagsContainerStyle, "empty:hidden", tagsContainerClassName), children: jsx(AnimatePresence, { mode: "popLayout", children: tags.map((tag, index) => {
+                        helperText: hasDropdown ? undefined : displayHelperText, disabled: isInputDisabled, className: inputClassName, role: hasDropdown ? "combobox" : undefined, "aria-expanded": hasDropdown ? isOpen : undefined, "aria-haspopup": hasDropdown ? "listbox" : undefined, "aria-autocomplete": hasDropdown ? "list" : undefined, "aria-controls": hasDropdown ? listboxId : undefined }), hasDropdown && (jsx(InputTagOptions, { isOpen: isOpen, onClose: handleCloseDropdown, triggerRef: wrapperRef, filteredOptions: filteredOptions, selectedTags: tags, highlightedIndex: highlightedIndex, setHighlightedIndex: setHighlightedIndex, onSelectOption: handleSelectOption, showSelectedIndicator: showSelectedIndicator, portal: portal, placement: placement, offset: offset, emptyMessage: emptyMessage, className: dropdownClassName, theme: theme, elevation: elevation, lift: lift, listboxId: listboxId }))] }), hasDropdown && displayHelperText && (jsx("p", { className: "text-sm text-[var(--color-text-muted)] mt-1.5", children: displayHelperText })), jsx("div", { className: cn(theme.tagsContainerStyle, "empty:hidden", tagsContainerClassName), children: jsx(AnimatePresence, { mode: "popLayout", children: tags.map((tag, index) => {
                         return (jsx(Tag, { size: size, onRemove: () => removeTag(index), disabled: disabled, className: tagClassName, children: tag }, `${tag}-${occurrenceMap[index]}`));
                     }) }) })] }));
 });

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

@@ -4,7 +4,8 @@ const inputTagTheme = {
     // Tags container style
     tagsContainerStyle: "flex flex-wrap gap-2 mt-2",
     // Dropdown styles - reuse from formsBaseTheme for consistency
-    dropdownStyle: formsBaseTheme.dropdownStyles.container + " py-1",
+    dropdownStyle: formsBaseTheme.dropdownStyles.container +
+        " py-1",
     optionStyle: formsBaseTheme.dropdownStyles.option,
     selectedOptionStyle: formsBaseTheme.dropdownStyles.optionSelected,
     highlightedOptionStyle: formsBaseTheme.dropdownStyles.optionHighlighted,

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

@@ -1,6 +1,7 @@
 import React from "react";
 import { InputState } from "../Input";
 import { TagSize } from "../../core/Tag";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 /**
  * Option type for InputTag suggestions dropdown
  */
@@ -74,6 +75,13 @@ export interface InputTagProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     offset?: number;
     /** Additional class name for the dropdown */
     dropdownClassName?: string;
+    /**
+     * Pin the suggestion 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 dropdown's base rung. */
+    lift?: boolean;
 }
 export type InputTagSize = TagSize;
 export type InputTagState = InputState;

package/dist/components/forms/Mention/Mention.js

@@ -1,3 +1,4 @@
+"use client";
 import React__default, { useMemo, useId, useState, useRef, useEffect, useCallback, useLayoutEffect, createElement } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { createPortal } from 'react-dom';
@@ -9,6 +10,7 @@ import { Tag } from '../../core/Tag/Tag.js';
 import { MenuItem } from '../../core/MenuItem/MenuItem.js';
 import { FormLabel } from '../FormLabel/FormLabel.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 import { normalizeSegments, setCaretAtOffset, getPlainTextOffset, parseDOMToSegments, serializeSegments, serializeSegmentsMasked, insertMentionIntoSegments, MENTION_ATTR } from './Mention.utils.js';
 
 // ---------------------------------------------------------------------------
@@ -75,9 +77,13 @@ const dropdownVariants = {
 // ---------------------------------------------------------------------------
 // Mention component
 // ---------------------------------------------------------------------------
-const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions: suggestionsProp, onSearch: onSearchProp, value: controlledValue, defaultValue = "", onChange, onMentionSelect, onMentionsChange, placeholder, size = "md", maxSuggestions = 8, className, wrapperClassName, dropdownClassName, theme: themeOverrides, state = "default", disabled = false, helperText, required, label, renderSuggestion, emptyMessage = "No results found", loading = false, mentionTagSize = "sm", mentionTagClassName, mentionTagRemovable = true, rows = 3, style: styleProp, ...props }, ref) => {
+const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions: suggestionsProp, onSearch: onSearchProp, value: controlledValue, defaultValue = "", onChange, onMentionSelect, onMentionsChange, placeholder, size = "md", maxSuggestions = 8, className, wrapperClassName, dropdownClassName, theme: themeOverrides, state = "default", disabled = false, helperText, required, label, renderSuggestion, emptyMessage = "No results found", loading = false, mentionTagSize = "sm", mentionTagClassName, mentionTagRemovable = true, rows = 3, style: styleProp, elevation, lift, ...props }, ref) => {
+    // Relative elevation: the suggestion dropdown lifts above its host surface
+    // (overlay base = 5) so a Mention inside a Popover/Modal still reads higher.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const theme = useMemo(() => ({ ...mentionTheme, ...(themeOverrides || {}) }), [themeOverrides]);
     const generatedId = useId();
+    const listboxId = `${generatedId}-listbox`;
     const isDisabled = state === "disabled" || disabled;
     const isInvalid = state === "invalid";
     const triggers = useMemo(() => {
@@ -681,7 +687,7 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
     // -----------------------------------------------------------------------
     // Dropdown portal content
     // -----------------------------------------------------------------------
-    const dropdownContent = (jsx(AnimatePresence, { mode: "wait", children: isDropdownOpen && (jsx(motion.div, { ref: dropdownRef, role: "listbox", "aria-label": "Suggestions", className: cn(theme.dropdownStyle, dropdownClassName), style: {
+    const dropdownContent = (jsx(AnimatePresence, { mode: "wait", children: isDropdownOpen && (jsx(motion.div, { ref: dropdownRef, id: listboxId, "data-flikkui-portal": "", role: "listbox", "aria-label": "Suggestions", className: cn(surfaceClasses(surfaceLevel, { translucent: true }), theme.dropdownStyle, dropdownClassName), style: {
                 position: "fixed",
                 top: `${dropdownPos.top}px`,
                 left: `${dropdownPos.left}px`,
@@ -689,13 +695,14 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                 maxWidth: "360px",
                 zIndex: 1000,
                 overscrollBehavior: "contain",
-            }, variants: dropdownVariants, initial: "initial", animate: "visible", exit: "exit", children: loading ? (jsx("div", { className: theme.loadingStyle, children: "Searching..." })) : filteredSuggestions.length === 0 ? (jsx("div", { className: theme.emptyMessageStyle, children: emptyMessage })) : (filteredSuggestions.map((suggestion, index) => renderSuggestionItem(suggestion, index))) })) }));
+            }, variants: dropdownVariants, initial: "initial", animate: "visible", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: loading ? (jsx("div", { className: theme.loadingStyle, children: "Searching..." })) : filteredSuggestions.length === 0 ? (jsx("div", { className: theme.emptyMessageStyle, children: emptyMessage })) : (filteredSuggestions.map((suggestion, index) => renderSuggestionItem(suggestion, index))) }) })) }));
     // -----------------------------------------------------------------------
     // Render
     // -----------------------------------------------------------------------
     const helperId = `${generatedId}-helper`;
-    return (jsxs("div", { className: cn(theme.wrapperStyle, wrapperClassName), children: [label && (jsx(FormLabel, { htmlFor: generatedId, state: isDisabled ? "disabled" : isInvalid ? "invalid" : "default", required: required, className: "mb-1.5", children: label })), jsx("div", { ref: wrapperRef, className: cn(theme.inputGroupStyle, isInvalid && theme.invalidStyle, isFocused &&
-                    (isInvalid ? theme.invalidFocusStyle : theme.inputGroupFocusStyle)), children: createElement("div", { ...props, key: editorKey, ref: setEditableRef, id: generatedId, contentEditable: !isDisabled, suppressContentEditableWarning: true, onInput: handleInput, onKeyDown: handleKeyDown, onClick: handleClick, onFocus: handleFocus, onBlur: handleBlur, onPaste: handlePaste, onSelect: handleSelect, onCompositionStart: handleCompositionStart, onCompositionEnd: handleCompositionEnd, role: "textbox", "aria-multiline": "true", "aria-autocomplete": "list", "aria-expanded": isDropdownOpen, "aria-haspopup": "listbox", "aria-placeholder": placeholder, "aria-required": required || undefined, "data-placeholder": placeholder, "aria-disabled": isDisabled || undefined, "aria-invalid": isInvalid || undefined, "aria-describedby": helperText ? helperId : undefined, className: cn(theme.editableStyle, theme.sizes[size], isContentEmpty &&
+    const labelId = `${generatedId}-label`;
+    return (jsxs("div", { className: cn(theme.wrapperStyle, wrapperClassName), children: [label && (jsx(FormLabel, { id: labelId, htmlFor: generatedId, state: isDisabled ? "disabled" : isInvalid ? "invalid" : "default", required: required, className: "mb-1.5", children: label })), jsx("div", { ref: wrapperRef, className: cn(theme.inputGroupStyle, isInvalid && theme.invalidStyle, isFocused &&
+                    (isInvalid ? theme.invalidFocusStyle : theme.inputGroupFocusStyle)), children: createElement("div", { ...props, key: editorKey, ref: setEditableRef, id: generatedId, contentEditable: !isDisabled, suppressContentEditableWarning: true, onInput: handleInput, onKeyDown: handleKeyDown, onClick: handleClick, onFocus: handleFocus, onBlur: handleBlur, onPaste: handlePaste, onSelect: handleSelect, onCompositionStart: handleCompositionStart, onCompositionEnd: handleCompositionEnd, role: "combobox", "aria-autocomplete": "list", "aria-expanded": isDropdownOpen, "aria-haspopup": "listbox", "aria-controls": listboxId, "aria-placeholder": placeholder, "aria-required": required || undefined, "data-placeholder": placeholder, "aria-disabled": isDisabled || undefined, "aria-invalid": isInvalid || undefined, "aria-describedby": helperText ? helperId : undefined, "aria-labelledby": label ? labelId : undefined, className: cn(theme.editableStyle, theme.sizes[size], isContentEmpty &&
                         "before:content-[attr(data-placeholder)] before:text-[var(--color-text-placeholder)] before:pointer-events-none before:absolute", isDisabled && "cursor-not-allowed opacity-60", className), style: {
                         minHeight: rows ? `${rows * 1.5}em` : undefined,
                         ...styleProp,

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

@@ -27,7 +27,8 @@ const mentionTheme = {
     // Dropdown container - reuses the shared dropdown styles
     // p-1 (not py-1) so MenuItem rows' rounded highlight insets evenly on all
     // sides instead of running flush to the container's left/right edges.
-    dropdownStyle: formsBaseTheme.dropdownStyles.container + " p-1",
+    dropdownStyle: formsBaseTheme.dropdownStyles.container +
+        " p-1",
     // Suggestion rows render via the shared MenuItem primitive (avatar →
     // startContent, label → children, description → subtitle). These two styles
     // are only used by the custom `renderSuggestion` escape hatch, which wraps

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

@@ -1,5 +1,6 @@
 import React from "react";
 import type { TagSize } from "../../core/Tag/Tag.types";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 /**
  * A single suggestion item displayed in the mention dropdown.
  */
@@ -157,4 +158,11 @@ export interface MentionProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     rows?: number;
     /** Label rendered above the mention input */
     label?: string;
+    /**
+     * Pin the suggestion 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 dropdown's base rung. */
+    lift?: boolean;
 }

package/dist/components/forms/Mention/Mention.utils.js

@@ -1,3 +1,4 @@
+"use client";
 // Data attribute used to identify mention nodes in the DOM
 const MENTION_ATTR = "data-mention-id";
 /**

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

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Radio dot spring animation
  * Scales in with a subtle bounce on select, fades out smoothly on deselect

package/dist/components/forms/Radio/Radio.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useId, useState, useEffect } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
@@ -53,7 +54,10 @@ const RadioComponent = React__default.forwardRef(({ id: idProp, name: nameProp,
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
-    return (jsxs("div", { className: cn(radioTheme.baseStyle, className), ...restProps, children: [jsxs("div", { className: cn(radioTheme.inputContainerStyle, radioTheme.sizes[size]), children: [jsx("input", { ref: ref, type: "radio", id: id, name: name, value: value, ...inputProps, onChange: handleChange, disabled: isDisabled, "aria-describedby": description ? `${id}-description` : undefined, "aria-invalid": isInvalid || undefined, "data-state": isDisabled ? "disabled" : isInvalid ? "invalid" : "default", className: cn("peer", radioTheme.inputStyle, radioTheme.sizes[size]) }), jsx(motion.div, { className: cn(radioTheme.dotStyle, radioTheme.dotSizes[size], isDisabled && "saturate-0 opacity-80"), initial: false, animate: isChecked ? "checked" : "unchecked", variants: shouldReduceMotion ? reducedMotionDotVariants : radioDotVariants })] }), (label || description) && (jsxs("label", { htmlFor: id, className: cn("cursor-pointer", isDisabled && "cursor-not-allowed"), children: [label && (typeof label === 'string' ? (jsx("span", { className: cn(formLabelTheme.baseStyle, formLabelTheme.stateStyles[state], "mb-0"), children: label })) : label), description && (typeof description === 'string' ? (jsx("div", { id: `${id}-description`, className: radioTheme.descriptionStyle, children: description })) : description)] }))] }));
+    return (jsxs("div", { className: cn(radioTheme.baseStyle, className), children: [jsxs("div", { className: cn(radioTheme.inputContainerStyle, radioTheme.sizes[size]), children: [jsx("input", { ref: ref, type: "radio", ...restProps, id: id, name: name, value: value, ...inputProps, onChange: handleChange, disabled: isDisabled, "aria-describedby": description ? `${id}-description` : undefined, "data-state": isDisabled ? "disabled" : isInvalid ? "invalid" : "default", className: cn("peer", radioTheme.inputStyle, radioTheme.sizes[size]) }), jsx(motion.div, { className: cn(radioTheme.dotStyle, radioTheme.dotSizes[size], isDisabled && "saturate-0 opacity-80"), initial: false, animate: isChecked ? "checked" : "unchecked", variants: shouldReduceMotion ? reducedMotionDotVariants : radioDotVariants })] }), (label || description) && (jsxs("label", { htmlFor: id, className: cn("cursor-pointer", isDisabled && "cursor-not-allowed"), children: [label && (typeof label === 'string' ? (jsx("span", { className: cn(formLabelTheme.baseStyle, 
+                        // Message-led invalid: option labels stay neutral (only the
+                        // group's asterisk + error message are red). Disabled still dims.
+                        formLabelTheme.stateStyles[state === "disabled" ? "disabled" : "default"], "mb-0"), children: label })) : label), description && (typeof description === 'string' ? (jsx("div", { id: `${id}-description`, className: radioTheme.descriptionStyle, children: description })) : description)] }))] }));
 });
 RadioComponent.displayName = "Radio";
 const Radio = Object.assign(RadioComponent, { Group: RadioGroup });

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

@@ -10,10 +10,11 @@ const radioTheme = {
         "border-[var(--color-border)] bg-[var(--color-surface)] " +
         // Default state - dark
         "dark:bg-[var(--color-surface-raised)] " +
-        // Checked state - light
-        "checked:border-[var(--color-primary)] checked:bg-white " +
+        // Checked state - fill with primary; the dot uses --color-primary-contrast so it
+        // stays visible even when the primary is light/white (matches Checkbox).
+        "checked:border-[var(--color-primary)] checked:bg-[var(--color-primary)] " +
         // Checked state - dark
-        "dark:checked:bg-[var(--color-surface)] " +
+        "dark:checked:border-[var(--color-primary)] dark:checked:bg-[var(--color-primary)] " +
         // Focus visible - light
         "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-primary-600)] " +
         // Focus visible - dark
@@ -23,10 +24,11 @@ const radioTheme = {
         "data-[state=disabled]:border-[var(--color-border)] data-[state=disabled]:bg-[var(--color-background-disabled)] data-[state=disabled]:cursor-not-allowed " +
         // Disabled state - dark
         "dark:disabled:bg-[var(--color-neutral-700)] dark:disabled:border-[var(--color-neutral-600)] " +
-        "dark:data-[state=disabled]:bg-[var(--color-neutral-700)] dark:data-[state=disabled]:border-[var(--color-neutral-600)] " +
-        // Invalid state
-        "data-[state=invalid]:border-[var(--color-danger)] data-[state=invalid]:focus-visible:outline-[var(--color-danger)]",
-    dotStyle: "absolute top-1/2 left-1/2 pointer-events-none rounded-full bg-[var(--color-primary)]",
+        "dark:data-[state=disabled]:bg-[var(--color-neutral-700)] dark:data-[state=disabled]:border-[var(--color-neutral-600)]",
+    // Invalid is message-led: the control stays neutral. The group's required
+    // asterisk + error message carry the error (see RadioGroup). `data-state=invalid`
+    // is still emitted on the input as an unstyled consumer/test hook.
+    dotStyle: "absolute top-1/2 left-1/2 pointer-events-none rounded-full bg-[var(--color-primary-contrast)]",
     dotSizes: {
         sm: "size-2.5 mt-0.25",
         md: "size-3",

package/dist/components/forms/Radio/RadioContext.js

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

package/dist/components/forms/Radio/RadioGroup.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useId, useState, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -33,7 +34,9 @@ const RadioGroup = React__default.forwardRef(({ value: controlledValue, defaultV
         size,
         state,
     }), [groupName, currentValue, size, state]);
-    const labelState = state === "invalid" ? "invalid" : state === "disabled" ? "disabled" : "default";
+    // Message-led invalid: the legend text stays neutral; the red required asterisk
+    // + the error message below carry the error (not a red field label).
+    const labelState = state === "disabled" ? "disabled" : "default";
     return (jsx(RadioGroupContext.Provider, { value: contextValue, children: jsxs("fieldset", { ref: ref, role: "radiogroup", "aria-labelledby": label ? labelId : undefined, "aria-describedby": description ? descriptionId : undefined, "aria-required": required || undefined, "aria-invalid": resolvedError ? true : undefined, "aria-errormessage": resolvedError ? errorId : undefined, className: cn("border-0 p-0 m-0", radioTheme.groupStyle, className), ...props, children: [label && (typeof label === 'string' ? (jsxs("legend", { id: labelId, className: cn(formLabelTheme.baseStyle, formLabelTheme.stateStyles[labelState]), children: [label, required && (jsx("span", { className: formLabelTheme.requiredIndicatorStyle, children: "*" }))] })) : label), description && (typeof description === 'string' ? (jsx("p", { id: descriptionId, className: radioTheme.groupDescriptionStyle, children: description })) : description), jsx("div", { className: cn(radioTheme.groupItemsStyle, orientation === "horizontal" && radioTheme.groupHorizontalStyle), children: children }), resolvedError && (typeof resolvedError === 'string' ? (jsx("p", { id: errorId, role: "alert", className: radioTheme.groupErrorStyle, children: resolvedError })) : resolvedError)] }) }));
 });
 RadioGroup.displayName = "Radio.Group";

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

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Floating toolbar animation variants
  * - Appears from bottom with subtle fade-in using spring animation