@flikk/ui 1.0.0-beta.23 → 1.0.0-beta.25

package/dist/components/forms/InputCounter/InputCounter.js

@@ -1,11 +1,12 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default, { useMemo, useEffect, useCallback } from 'react';
+import React__default, { useId, useMemo, useEffect, useCallback } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { inputCounterTheme } from './InputCounter.theme.js';
 import { Button } from '../../core/Button/Button.js';
 import { SlidingNumber } from '../../core/SlidingNumber/SlidingNumber.js';
 import { cn } from '../../../utils/cn.js';
 import { MinusIcon, PlusIcon } from '@heroicons/react/24/outline';
+import { FormLabel } from '../FormLabel/FormLabel.js';
 
 /**
  * InputCounter component with animated number display
@@ -33,9 +34,12 @@ import { MinusIcon, PlusIcon } from '@heroicons/react/24/outline';
  * );
  * ```
  */
-const InputCounter = React__default.forwardRef(({ value, onChange, min, max, step = 1, disabled = false, decimalPlaces, formatNumber = (n) => n.toString(), className, buttonProps, theme, transition = { type: "spring", bounce: 0, stiffness: 300, damping: 30 }, "aria-label": ariaLabel = "Counter", onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...props }, ref) => {
+const InputCounter = React__default.forwardRef(({ value, onChange, state = "default", label, helperText, min, max, step = 1, disabled = false, decimalPlaces, formatNumber = (n) => n.toString(), className, buttonProps, theme, transition = { type: "spring", bounce: 0, stiffness: 300, damping: 30 }, "aria-label": ariaLabel = "Counter", onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...props }, ref) => {
     const shouldReduceMotion = useReducedMotion();
     const shouldDisableAnimations = !!shouldReduceMotion;
+    const generatedId = useId();
+    const isDisabled = state === "disabled" || disabled;
+    const isInvalid = state === "invalid";
     // Auto-detect decimal places from step if not explicitly provided
     const autoDecimalPlaces = useMemo(() => {
         if (decimalPlaces !== undefined)
@@ -68,12 +72,12 @@ const InputCounter = React__default.forwardRef(({ value, onChange, min, max, ste
             needsUpdate = true;
         }
         if (needsUpdate) {
-            onChange(clampedValue);
+            onChange === null || onChange === void 0 ? void 0 : onChange(clampedValue);
         }
     }, [min, max, value, onChange]);
     // Handle increment
     const handleIncrement = useCallback(() => {
-        if (disabled)
+        if (isDisabled)
             return;
         const newValue = value + step;
         // Round to avoid floating point precision errors
@@ -86,11 +90,11 @@ const InputCounter = React__default.forwardRef(({ value, onChange, min, max, ste
             }
             return;
         }
-        onChange(roundedValue);
-    }, [value, step, max, disabled, onChange]);
+        onChange === null || onChange === void 0 ? void 0 : onChange(roundedValue);
+    }, [value, step, max, isDisabled, onChange]);
     // Handle decrement
     const handleDecrement = useCallback(() => {
-        if (disabled)
+        if (isDisabled)
             return;
         const newValue = value - step;
         // Round to avoid floating point precision errors
@@ -103,12 +107,12 @@ const InputCounter = React__default.forwardRef(({ value, onChange, min, max, ste
             }
             return;
         }
-        onChange(roundedValue);
-    }, [value, step, min, disabled, onChange]);
+        onChange === null || onChange === void 0 ? void 0 : onChange(roundedValue);
+    }, [value, step, min, isDisabled, onChange]);
     // Keyboard support
     useEffect(() => {
         const handleKeyDown = (event) => {
-            if (disabled)
+            if (isDisabled)
                 return;
             // Check if the counter is focused
             const target = event.target;
@@ -127,20 +131,20 @@ const InputCounter = React__default.forwardRef(({ value, onChange, min, max, ste
                     event.preventDefault();
                     const pageUpValue = value + step * 10;
                     if (max === undefined || pageUpValue <= max) {
-                        onChange(pageUpValue);
+                        onChange === null || onChange === void 0 ? void 0 : onChange(pageUpValue);
                     }
                     else if (max !== undefined) {
-                        onChange(max);
+                        onChange === null || onChange === void 0 ? void 0 : onChange(max);
                     }
                     break;
                 case "PageDown":
                     event.preventDefault();
                     const pageDownValue = value - step * 10;
                     if (min === undefined || pageDownValue >= min) {
-                        onChange(pageDownValue);
+                        onChange === null || onChange === void 0 ? void 0 : onChange(pageDownValue);
                     }
                     else if (min !== undefined) {
-                        onChange(min);
+                        onChange === null || onChange === void 0 ? void 0 : onChange(min);
                     }
                     break;
             }
@@ -152,15 +156,18 @@ const InputCounter = React__default.forwardRef(({ value, onChange, min, max, ste
         step,
         min,
         max,
-        disabled,
+        isDisabled,
         onChange,
         handleIncrement,
         handleDecrement,
     ]);
     // Check if buttons should be disabled
-    const canDecrement = !disabled && (min === undefined || value > min);
-    const canIncrement = !disabled && (max === undefined || value < max);
-    return (jsxs(motion.div, { ref: ref, "data-counter": "true", layout: true, transition: shouldDisableAnimations ? undefined : transition, className: cn(mergedTheme.baseStyle, className), role: "spinbutton", "aria-label": ariaLabel, "aria-valuenow": value, "aria-valuemin": min, "aria-valuemax": max, "aria-disabled": disabled, tabIndex: disabled ? -1 : 0, ...props, children: [jsx(motion.div, { className: mergedTheme.buttonWrapperStyle, whileHover: !disabled && !shouldDisableAnimations ? { scale: 1.05 } : undefined, whileTap: !disabled && !shouldDisableAnimations ? { scale: 0.95 } : undefined, children: jsx(Button, { size: "sm", variant: "link", iconOnly: true, ...buttonProps, onClick: handleDecrement, disabled: !canDecrement, "aria-label": "Decrement", children: jsx(MinusIcon, { className: "size-4 text-[var(--color-text-primary)]", strokeWidth: 2 }) }) }), jsx(SlidingNumber, { value: value, decimalPlaces: autoDecimalPlaces, className: mergedTheme.numberStyle, transition: transition }), jsx(motion.div, { className: mergedTheme.buttonWrapperStyle, whileHover: !disabled && !shouldDisableAnimations ? { scale: 1.05 } : undefined, whileTap: !disabled && !shouldDisableAnimations ? { scale: 0.95 } : undefined, children: jsx(Button, { size: "sm", variant: "link", iconOnly: true, ...buttonProps, onClick: handleIncrement, disabled: !canIncrement, "aria-label": "Increment", children: jsx(PlusIcon, { className: "size-4 text-[var(--color-text-primary)]", strokeWidth: 2 }) }) })] }));
+    const canDecrement = !isDisabled && (min === undefined || value > min);
+    const canIncrement = !isDisabled && (max === undefined || value < max);
+    const helperId = `${generatedId}-helper`;
+    return (jsxs("div", { className: "flex flex-col", children: [label && (typeof label === "string" ? (jsx(FormLabel, { htmlFor: `${generatedId}-counter`, state: isDisabled ? "disabled" : isInvalid ? "invalid" : "default", className: "mb-1.5", children: label })) : (jsx("div", { className: "mb-1.5", children: label }))), jsxs(motion.div, { ref: ref, id: `${generatedId}-counter`, "data-counter": "true", layout: true, transition: shouldDisableAnimations ? undefined : transition, className: cn(mergedTheme.baseStyle, isInvalid && "ring-1 ring-[var(--color-danger)]", className), role: "spinbutton", "aria-label": ariaLabel, "aria-valuenow": value, "aria-valuemin": min, "aria-valuemax": max, "aria-disabled": isDisabled, "aria-invalid": isInvalid || undefined, "aria-describedby": helperText ? helperId : undefined, tabIndex: isDisabled ? -1 : 0, ...props, children: [jsx(motion.div, { className: mergedTheme.buttonWrapperStyle, whileHover: !isDisabled && !shouldDisableAnimations ? { scale: 1.05 } : undefined, whileTap: !isDisabled && !shouldDisableAnimations ? { scale: 0.95 } : undefined, children: jsx(Button, { size: "sm", variant: "link", iconOnly: true, ...buttonProps, onClick: handleDecrement, disabled: !canDecrement, "aria-label": "Decrement", children: jsx(MinusIcon, { className: "size-4 text-[var(--color-text-primary)]", strokeWidth: 2 }) }) }), jsx(SlidingNumber, { value: value, decimalPlaces: autoDecimalPlaces, className: mergedTheme.numberStyle, transition: transition }), jsx(motion.div, { className: mergedTheme.buttonWrapperStyle, whileHover: !isDisabled && !shouldDisableAnimations ? { scale: 1.05 } : undefined, whileTap: !isDisabled && !shouldDisableAnimations ? { scale: 0.95 } : undefined, children: jsx(Button, { size: "sm", variant: "link", iconOnly: true, ...buttonProps, onClick: handleIncrement, disabled: !canIncrement, "aria-label": "Increment", children: jsx(PlusIcon, { className: "size-4 text-[var(--color-text-primary)]", strokeWidth: 2 }) }) })] }), helperText && (jsx("div", { id: helperId, className: cn("text-sm mt-1", isInvalid
+                    ? "text-[var(--color-danger)]"
+                    : "text-[var(--color-text-muted)]"), children: helperText }))] }));
 });
 InputCounter.displayName = "InputCounter";
 

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

@@ -1,6 +1,7 @@
 import React from 'react';
 import type { Transition } from 'motion/react';
 import { ButtonProps } from '../../core/Button/Button.types';
+export type InputCounterState = 'default' | 'disabled' | 'invalid';
 /**
  * InputCounter component props
  * @property {number} value - Current counter value (controlled)
@@ -18,7 +19,13 @@ export interface InputCounterProps extends Omit<React.HTMLAttributes<HTMLDivElem
     /** Current counter value (controlled) */
     value: number;
     /** Callback when value changes */
-    onChange: (value: number) => void;
+    onChange?: (value: number) => void;
+    /** Validation/interaction state */
+    state?: InputCounterState;
+    /** Field label rendered above the counter */
+    label?: React.ReactNode;
+    /** Helper text rendered below the counter */
+    helperText?: React.ReactNode;
     /** Minimum allowed value (optional) */
     min?: number;
     /** Maximum allowed value (optional) */

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

@@ -16,4 +16,4 @@ import { InputCreditCardProps } from "./InputCreditCard.types";
  * />
  * ```
  */
-export declare const InputCreditCard: React.ForwardRefExoticComponent<InputCreditCardProps & React.RefAttributes<HTMLDivElement>>;
+export declare const InputCreditCard: React.ForwardRefExoticComponent<InputCreditCardProps & React.RefAttributes<HTMLFieldSetElement>>;

package/dist/components/forms/InputCreditCard/InputCreditCard.js

@@ -1,8 +1,8 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default, { useMemo, useState, useCallback } from 'react';
+import React__default, { useState, useEffect, useMemo, useCallback, useId } from 'react';
 import { Input } from '../Input/Input.js';
-import { FormLabel } from '../FormLabel/FormLabel.js';
 import { InputCreditCardTheme } from './InputCreditCard.theme.js';
+import { formsBaseTheme } from '../forms.theme.js';
 
 /**
  * InputCreditCard component for collecting credit card information
@@ -20,7 +20,17 @@ import { InputCreditCardTheme } from './InputCreditCard.theme.js';
  * />
  * ```
  */
-const InputCreditCard = React__default.forwardRef(({ onCardNumberChange, onExpiryDateChange, onCvcChange, expiryDateLabel = "MM / YY", cvcLabel = "CVC", legendText = "Payment Information", cardNumberInputProps = {}, expiryDateInputProps = {}, cvcInputProps = {}, className = "", theme = {}, }, ref) => {
+const InputCreditCard = React__default.forwardRef(({ state = 'default', error, onCardNumberChange, onExpiryDateChange, onCvcChange, expiryDateLabel = "MM / YY", cvcLabel = "CVC", legendText = "Payment Information", cardNumberInputProps = {}, expiryDateInputProps = {}, cvcInputProps = {}, className = "", theme = {}, }, ref) => {
+    var _a;
+    const isDisabled = state === 'disabled';
+    // Clear the error visually as soon as the user starts re-entering after an error.
+    // Resets when the parent sets state back to 'invalid' (e.g. on re-submit).
+    const [isDirtyAfterError, setIsDirtyAfterError] = useState(false);
+    useEffect(() => {
+        if (state === 'invalid')
+            setIsDirtyAfterError(false);
+    }, [state]);
+    const isInvalid = state === 'invalid' && !isDirtyAfterError;
     // Merge the default theme with the provided theme overrides
     const mergedTheme = useMemo(() => ({
         ...InputCreditCardTheme,
@@ -43,18 +53,21 @@ const InputCreditCard = React__default.forwardRef(({ onCardNumberChange, onExpir
     const handleCardNumberChange = useCallback((e) => {
         const newCardNumber = e.target.value;
         setCardNumber(newCardNumber);
+        setIsDirtyAfterError(true);
         onCardNumberChange === null || onCardNumberChange === void 0 ? void 0 : onCardNumberChange(newCardNumber);
     }, [onCardNumberChange]);
     // Handle expiry date change
     const handleExpiryDateChange = useCallback((e) => {
         const newExpiryDate = e.target.value;
         setExpiryDate(newExpiryDate);
+        setIsDirtyAfterError(true);
         onExpiryDateChange === null || onExpiryDateChange === void 0 ? void 0 : onExpiryDateChange(newExpiryDate);
     }, [onExpiryDateChange]);
     // Handle CVC change
     const handleCvcChange = useCallback((e) => {
         const newCvc = e.target.value;
         setCvc(newCvc);
+        setIsDirtyAfterError(true);
         onCvcChange === null || onCvcChange === void 0 ? void 0 : onCvcChange(newCvc);
     }, [onCvcChange]);
     // Handle focus states
@@ -64,12 +77,17 @@ const InputCreditCard = React__default.forwardRef(({ onCardNumberChange, onExpir
     const handleBlur = useCallback(() => {
         setFocused(null);
     }, []);
-    // Create unique IDs for accessibility
-    useMemo(() => `card-fieldset-${Math.random().toString(36).substring(2, 9)}`, []);
-    const cardNumberId = useMemo(() => `card-number-${Math.random().toString(36).substring(2, 9)}`, []);
-    const expiryDateId = useMemo(() => `expiry-date-${Math.random().toString(36).substring(2, 9)}`, []);
-    const cvcId = useMemo(() => `cvc-${Math.random().toString(36).substring(2, 9)}`, []);
-    return (jsxs("div", { ref: ref, className: `w-full ${className}`, "data-testid": "input-credit-card-fieldset", children: [jsx(FormLabel, { htmlFor: cardNumberId, className: mergedTheme.legendStyles, children: legendText }), jsxs("div", { className: `grid gap-0 ${mergedTheme.contentStyles}`, "data-testid": "input-credit-card-content", children: [jsx("div", { className: "w-full relative focus-within:z-10", "data-testid": "input-card-number", children: jsx(Input, { id: cardNumberId, type: "creditCard", value: cardNumber, onChange: handleCardNumberChange, placeholder: "Card Number", "aria-label": "card number", onFocus: () => handleFocus("cardNumber"), onBlur: handleBlur, inputGroupClassName: "rounded-b-none", ...cardNumberInputProps }) }), jsxs("div", { className: "grid grid-cols-1 sm:grid-cols-2 w-full -mt-px relative", children: [jsx("div", { className: `${mergedTheme.expiryDateWrapperStyles || ""} w-full sm:pr-0`, "data-testid": "input-expiry-date relative focus-within:z-10", children: jsx(Input, { id: expiryDateId, type: "expiryDate", value: expiryDate, onChange: handleExpiryDateChange, placeholder: expiryDateLabel, "aria-label": expiryDateLabel, onFocus: () => handleFocus("expiryDate"), onBlur: handleBlur, inputGroupClassName: "sm:rounded-bl-md rounded-t-none sm:rounded-tr-none sm:rounded-br-none relative focus-within:z-10", ...expiryDateInputProps }) }), jsx("div", { className: `${mergedTheme.cvcWrapperStyles || ""} w-full`, "data-testid": "input-cvc relative focus-within:z-10", children: jsx(Input, { id: cvcId, type: "tel", maxLength: 3, pattern: "[0-9]*", inputMode: "numeric", value: cvc, onChange: handleCvcChange, placeholder: cvcLabel, "aria-label": cvcLabel, onFocus: () => handleFocus("cvc"), onBlur: handleBlur, inputGroupClassName: " sm:rounded-br-md rounded-t-none rounded-bl-md sm:rounded-bl-none relative focus-within:z-10", ...cvcInputProps }) })] })] })] }));
+    const instanceId = useId();
+    const cardNumberId = `${instanceId}-card-number`;
+    const expiryDateId = `${instanceId}-expiry-date`;
+    const cvcId = `${instanceId}-cvc`;
+    const fieldState = isInvalid ? 'invalid' : isDisabled ? 'disabled' : 'default';
+    // Merge top-level state into each field's props; strip per-field helperText
+    // so only the consolidated error message is shown at the bottom.
+    const { helperText: _cn, ...cardProps } = { state: fieldState, ...cardNumberInputProps };
+    const { helperText: _ex, ...expiryProps } = { state: fieldState, ...expiryDateInputProps };
+    const { helperText: _cv, ...cvcProps } = { state: fieldState, ...cvcInputProps };
+    return (jsxs("fieldset", { ref: ref, className: `w-full border-0 m-0 p-0 ${isInvalid ? 'state-invalid' : ''} ${className}`, "data-testid": "input-credit-card-fieldset", children: [jsx("legend", { className: `block text-sm/6 font-medium mb-2 text-[var(--color-text-primary)] ${(_a = mergedTheme.legendStyles) !== null && _a !== void 0 ? _a : ""}`, children: legendText }), jsxs("div", { className: `grid gap-0 ${mergedTheme.contentStyles}`, "data-testid": "input-credit-card-content", children: [jsx("div", { className: "w-full relative focus-within:z-10", "data-testid": "input-card-number", children: jsx(Input, { id: cardNumberId, type: "creditCard", value: cardNumber, onChange: handleCardNumberChange, placeholder: "Card Number", "aria-label": "card number", onFocus: () => handleFocus("cardNumber"), onBlur: handleBlur, inputGroupClassName: "rounded-b-none", ...cardProps }) }), jsxs("div", { className: "grid grid-cols-1 sm:grid-cols-2 w-full -mt-px relative", children: [jsx("div", { className: `${mergedTheme.expiryDateWrapperStyles || ""} w-full sm:pr-0`, "data-testid": "input-expiry-date relative focus-within:z-10", children: jsx(Input, { id: expiryDateId, type: "expiryDate", value: expiryDate, onChange: handleExpiryDateChange, placeholder: expiryDateLabel, "aria-label": expiryDateLabel, onFocus: () => handleFocus("expiryDate"), onBlur: handleBlur, inputGroupClassName: "sm:rounded-bl-md rounded-t-none sm:rounded-tr-none sm:rounded-br-none relative focus-within:z-10", ...expiryProps }) }), jsx("div", { className: `${mergedTheme.cvcWrapperStyles || ""} w-full`, "data-testid": "input-cvc relative focus-within:z-10", children: jsx(Input, { id: cvcId, type: "tel", maxLength: 3, pattern: "[0-9]*", inputMode: "numeric", value: cvc, onChange: handleCvcChange, placeholder: cvcLabel, "aria-label": cvcLabel, onFocus: () => handleFocus("cvc"), onBlur: handleBlur, inputGroupClassName: " sm:rounded-br-md rounded-t-none rounded-bl-md sm:rounded-bl-none relative focus-within:z-10", ...cvcProps }) })] })] }), error && (jsx("p", { className: formsBaseTheme.helperText, children: error }))] }));
 });
 InputCreditCard.displayName = "InputCreditCard";
 

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

@@ -1,3 +1,4 @@
+import React from 'react';
 import { InputProps, InputTheme } from '../Input/Input.types';
 /**
  * InputCreditCard component props
@@ -10,6 +11,10 @@ import { InputProps, InputTheme } from '../Input/Input.types';
  * @property {InputCreditCardThemeOverrides} theme - Theme overrides for the credit card input
  */
 export interface InputCreditCardProps {
+    /** Visual/validation state of the entire card group */
+    state?: 'default' | 'disabled' | 'invalid';
+    /** Consolidated error message shown below all fields */
+    error?: React.ReactNode;
     /** Callback when card number changes */
     onCardNumberChange?: (cardNumber: string) => void;
     /** Callback when expiry date changes */

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

@@ -21,11 +21,16 @@ 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, 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;
@@ -33,14 +38,14 @@ const InputOTP = React__default.forwardRef(({ length = 6, value = '', onChange,
     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 +63,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 +104,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 +122,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 +131,15 @@ 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';
+    // Resolved helper text to display — prefer helperText, fall back to error
+    const displayedHelperText = 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 +164,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-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-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-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

@@ -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,30 @@ 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
+     * @deprecated Use `state='invalid'` with `helperText` instead.
      */
     error?: string;
     /**

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

@@ -1,4 +1,4 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+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,35 +11,8 @@ 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';
 
-/**
- * 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
  */
@@ -97,16 +70,16 @@ 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: 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);
     }

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

@@ -33,9 +33,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 */

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

@@ -1,11 +1,12 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { useMemo, useState, useRef, useEffect, useCallback, useLayoutEffect } from 'react';
+import React__default, { useMemo, useId, useState, useRef, useEffect, useCallback, useLayoutEffect } from 'react';
 import { createPortal } from 'react-dom';
 import { AnimatePresence, motion } from 'motion/react';
 import { mentionTheme } from './Mention.theme.js';
 import { cn } from '../../../utils/cn.js';
 import { Avatar } from '../../core/Avatar/Avatar.js';
 import { Tag } from '../../core/Tag/Tag.js';
+import { FormLabel } from '../FormLabel/FormLabel.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
 import { normalizeSegments, setCaretAtOffset, getPlainTextOffset, parseDOMToSegments, serializeSegments, serializeSegmentsMasked, insertMentionIntoSegments, MENTION_ATTR } from './Mention.utils.js';
 
@@ -73,8 +74,11 @@ 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, disabled = false, renderSuggestion, emptyMessage = "No results found", loading = false, mentionTagSize = "sm", mentionTagClassName, rows = 3, ...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, rows = 3, ...props }, ref) => {
     const theme = useMemo(() => ({ ...mentionTheme, ...(themeOverrides || {}) }), [themeOverrides]);
+    const generatedId = useId();
+    const isDisabled = state === "disabled" || disabled;
+    const isInvalid = state === "invalid";
     const triggers = useMemo(() => {
         if (triggersProp && triggersProp.length > 0)
             return triggersProp;
@@ -150,7 +154,7 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         if (!activeMention || !(activeTriggerConfig === null || activeTriggerConfig === void 0 ? void 0 : activeTriggerConfig.onSearch))
             return;
         activeTriggerConfig.onSearch(activeMention.query);
-    }, [activeMention === null || activeMention === void 0 ? void 0 : activeMention.query, activeMention === null || activeMention === void 0 ? void 0 : activeMention.trigger]); // eslint-disable-line react-hooks/exhaustive-deps
+    }, [activeMention === null || activeMention === void 0 ? void 0 : activeMention.query, activeMention === null || activeMention === void 0 ? void 0 : activeMention.trigger, activeTriggerConfig]);
     // Reset highlighted index when suggestions change
     useEffect(() => {
         setHighlightedIndex(filteredSuggestions.length > 0 ? 0 : -1);
@@ -596,11 +600,14 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
     // -----------------------------------------------------------------------
     // Render
     // -----------------------------------------------------------------------
-    return (jsxs("div", { className: cn(theme.wrapperStyle, wrapperClassName), children: [jsx("div", { ref: wrapperRef, className: cn(theme.inputGroupStyle, isFocused && theme.inputGroupFocusStyle), children: jsx("div", { ref: setEditableRef, contentEditable: !disabled, 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, "data-placeholder": placeholder, "aria-disabled": disabled || 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 dark:before:text-[var(--color-neutral-500)]", disabled && "cursor-not-allowed opacity-60", className), style: {
+    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, isFocused && theme.inputGroupFocusStyle, isInvalid && "border-[var(--color-danger)] ring-1 ring-[var(--color-danger)]"), children: jsx("div", { 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 &&
+                        "before:content-[attr(data-placeholder)] before:text-[var(--color-text-placeholder)] before:pointer-events-none before:absolute dark:before:text-[var(--color-neutral-500)]", isDisabled && "cursor-not-allowed opacity-60", className), style: {
                         minHeight: rows ? `${rows * 1.5}em` : undefined,
                         position: "relative",
-                    }, ...props, children: renderedSegments }) }), isClient && createPortal(dropdownContent, document.body)] }));
+                    }, ...props, children: renderedSegments }) }), helperText && (jsx("div", { id: helperId, className: cn("text-sm mt-1", isInvalid
+                    ? "text-[var(--color-danger)]"
+                    : "text-[var(--color-text-muted)]"), children: helperText })), isClient && createPortal(dropdownContent, document.body)] }));
 });
 Mention.displayName = "Mention";
 

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

@@ -100,6 +100,7 @@ export interface MentionTheme {
  * Partial theme overrides for the Mention component.
  */
 export type MentionThemeOverrides = Partial<MentionTheme>;
+export type MentionState = "default" | "disabled" | "invalid";
 /**
  * Props for the Mention component.
  */
@@ -134,8 +135,14 @@ export interface MentionProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     dropdownClassName?: string;
     /** Theme overrides */
     theme?: MentionThemeOverrides;
+    /** Validation/interaction state */
+    state?: MentionState;
     /** Whether the mention input is disabled */
     disabled?: boolean;
+    /** Helper text rendered below the mention input */
+    helperText?: React.ReactNode;
+    /** Whether the field is required */
+    required?: boolean;
     /** Custom renderer for suggestion items */
     renderSuggestion?: (suggestion: MentionSuggestion, isHighlighted: boolean, trigger: string) => React.ReactNode;
     /** Message shown when no suggestions match */
@@ -148,4 +155,6 @@ export interface MentionProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     mentionTagClassName?: string;
     /** Number of visible text rows (controls min-height) */
     rows?: number;
+    /** Label rendered above the mention input */
+    label?: string;
 }