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

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,26 +22,36 @@ import { inputOTPTheme } from './InputOTP.theme.js';
  * />
  * ```
  */
-const InputOTP = React__default.forwardRef(({ length = 6, value = '', onChange, onComplete, disabled = false, label, helperText, error, autoFocus = true, className, ...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;
-    // Internal state for uncontrolled usage
-    const [internalValue, setInternalValue] = useState('');
+    const generatedId = React__default.useId();
+    const helperTextId = `${idProp !== null && idProp !== void 0 ? idProp : generatedId}-helper`;
+    // Derive unified state flags for backward compat
+    const isDisabled = state === 'disabled' || disabled;
+    const isInvalid = state === 'invalid' || !!error;
+    // 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
     useEffect(() => {
-        if (autoFocus && inputRefs.current[0] && !disabled) {
+        if (autoFocus && inputRefs.current[0] && !isDisabled) {
             inputRefs.current[0].focus();
         }
-    }, [autoFocus, disabled]);
+    }, [autoFocus, isDisabled]);
     // Handle input change
     const handleChange = useCallback((index, newValue) => {
         var _a;
-        if (disabled)
+        if (isDisabled)
             return;
         // Only allow single character (take last character if multiple)
         const char = newValue.slice(-1);
@@ -58,11 +69,11 @@ const InputOTP = React__default.forwardRef(({ length = 6, value = '', onChange,
         if (newValueString.length === length) {
             onComplete === null || onComplete === void 0 ? void 0 : onComplete(newValueString);
         }
-    }, [disabled, valueArray, length, setValue, onComplete]);
+    }, [isDisabled, valueArray, length, setValue, onComplete]);
     // Handle key down for navigation and deletion
     const handleKeyDown = useCallback((index, event) => {
         var _a, _b, _c, _d, _e;
-        if (disabled)
+        if (isDisabled)
             return;
         switch (event.key) {
             case 'Backspace':
@@ -99,11 +110,11 @@ const InputOTP = React__default.forwardRef(({ length = 6, value = '', onChange,
                 (_e = inputRefs.current[length - 1]) === null || _e === void 0 ? void 0 : _e.focus();
                 break;
         }
-    }, [disabled, valueArray, length, handleChange]);
+    }, [isDisabled, valueArray, length, handleChange]);
     // Handle paste
     const handlePaste = useCallback((event) => {
         var _a;
-        if (disabled)
+        if (isDisabled)
             return;
         event.preventDefault();
         const pastedData = event.clipboardData.getData('text').slice(0, length);
@@ -117,7 +128,7 @@ const InputOTP = React__default.forwardRef(({ length = 6, value = '', onChange,
                 onComplete === null || onComplete === void 0 ? void 0 : onComplete(pastedData);
             }
         }
-    }, [disabled, length, setValue, onComplete]);
+    }, [isDisabled, length, setValue, onComplete]);
     // Handle focus and blur (simplified since we removed focus state)
     const handleFocus = useCallback((index) => {
         // Focus logic can be added here if needed
@@ -126,11 +137,21 @@ const InputOTP = React__default.forwardRef(({ length = 6, value = '', onChange,
         // Blur logic can be added here if needed
     }, []);
     // State class for CSS selectors (matches Input component pattern)
-    const stateClass = error
+    const stateClass = isInvalid
         ? "state-invalid"
-        : disabled
+        : isDisabled
             ? "state-disabled"
             : "state-default";
+    // Resolved label state for FormLabel
+    const labelState = isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default';
+    // 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);
@@ -155,20 +176,20 @@ const InputOTP = React__default.forwardRef(({ length = 6, value = '', onChange,
             });
         }
     };
-    return (jsxs("div", { ref: ref, className: wrapperClasses, ...props, children: [label && (jsx(FormLabel, { htmlFor: `otp-input-0`, state: error ? "invalid" : disabled ? "disabled" : "default", children: label })), jsx("div", { className: containerClasses, children: length === 6 ? (
+    return (jsxs("div", { ref: ref, className: wrapperClasses, ...props, children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: "otp-input-0", state: labelState, children: label })) : (label)), jsx("div", { className: containerClasses, children: length === 6 ? (
                 // 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: disabled, 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: disabled, 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: disabled, maxLength: 1, className: theme.inputStyle, inputGroupClassName: getInputClasses(index), wrapperClassName: "space-y-0 w-auto" }, index))) })) }), (error || helperText) && (jsx("div", { className: cn(theme.helperText), children: error || helperText }))] }));
+                        }, 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.theme.js

@@ -10,7 +10,7 @@ const inputOTPTheme = {
     // OTP input container
     containerStyle: 'flex items-center gap-3',
     // Individual input field styles with design tokens
-    inputStyle: 'text-center text-lg text-[var(--color-text-primary)] h-full',
+    inputStyle: 'text-center text-lg text-[var(--color-text-primary)] h-full !p-0',
     // Input group wrapper for grouped inputs (overrides default Input styling)
     inputGroupStyle: 'w-10 min-w-10 h-10 min-h-10 sm:w-12 sm:min-w-12 sm:h-12 sm:min-h-12',
     // Separator between input groups

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

@@ -1,13 +1,21 @@
-export interface InputOTPProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+/**
+ * State variants for the InputOTP component
+ */
+export type InputOTPState = 'default' | 'disabled' | 'invalid';
+export interface InputOTPProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
     /**
      * Number of OTP input fields
      * @default 6
      */
     length?: number;
     /**
-     * Current OTP value
+     * Current OTP value (controlled)
      */
     value?: string;
+    /**
+     * Default OTP value (uncontrolled)
+     */
+    defaultValue?: string;
     /**
      * Callback when OTP value changes
      */
@@ -16,21 +24,36 @@ export interface InputOTPProps extends Omit<React.HTMLAttributes<HTMLDivElement>
      * Callback when OTP is complete (all fields filled)
      */
     onComplete?: (value: string) => void;
+    /**
+     * Visual and functional state of the OTP input group.
+     * Use 'disabled' instead of the deprecated `disabled` boolean prop.
+     * Use 'invalid' instead of the deprecated `error` string prop.
+     * @default 'default'
+     */
+    state?: InputOTPState;
     /**
      * Whether the input is disabled
+     * @deprecated Use `state='disabled'` instead.
      * @default false
      */
     disabled?: boolean;
     /**
      * Label for the OTP input group
      */
-    label?: string;
+    label?: React.ReactNode;
     /**
      * Helper text below the inputs
      */
-    helperText?: string;
+    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 `errorMessage` instead.
      */
     error?: string;
     /**

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

@@ -1,4 +1,5 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+"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';
 import { createPortal } from 'react-dom';
@@ -11,43 +12,20 @@ import { inputTagTheme } from './InputTag.theme.js';
 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';
 
-/**
- * Hook to detect dark mode state from document
- */
-const useDarkMode = () => {
-    const [isDark, setIsDark] = useState(false);
-    useEffect(() => {
-        if (typeof document === "undefined")
-            return;
-        const checkDarkMode = () => {
-            const hasDarkClass = document.documentElement.classList.contains("dark") ||
-                document.body.classList.contains("dark") ||
-                document.querySelector(".dark") !== null;
-            setIsDark(hasDarkClass);
-        };
-        checkDarkMode();
-        const observer = new MutationObserver(checkDarkMode);
-        observer.observe(document.documentElement, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        observer.observe(document.body, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        return () => observer.disconnect();
-    }, []);
-    return isDark;
-};
 /**
  * Default filter function for suggestions
  */
 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();
@@ -87,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
@@ -97,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 })) : (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));
-            })) })) }));
+            }, 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;
 };
@@ -154,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,
@@ -162,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("");
@@ -171,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;
@@ -344,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]);
@@ -417,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);
         }
@@ -480,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-xs 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
  */
@@ -33,9 +34,9 @@ export interface InputTagProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     /** The state of the input */
     state?: InputTagState;
     /** Label for the input */
-    label?: string;
+    label?: React.ReactNode;
     /** Helper text displayed below the tags */
-    helperText?: string;
+    helperText?: React.ReactNode;
     /** Placeholder text for the input */
     placeholder?: string;
     /** Whether the input is disabled */
@@ -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.d.ts

@@ -1,3 +1,3 @@
 import React from "react";
 import type { MentionProps } from "./Mention.types";
-export declare const Mention: React.ForwardRefExoticComponent<MentionProps & React.RefAttributes<HTMLTextAreaElement>>;
+export declare const Mention: React.ForwardRefExoticComponent<MentionProps & React.RefAttributes<HTMLDivElement>>;