@flikk/ui 1.0.0-beta.22 → 1.0.0-beta.24

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

@@ -1,3 +1,5 @@
+import React from "react";
+export type FileUploadState = "default" | "disabled" | "invalid";
 /**
  * FileUpload component props
  * Supports both click-to-upload and drag-and-drop
@@ -22,11 +24,24 @@ export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElemen
      * Maximum number of files (when multiple is true)
      */
     maxFiles?: number;
+    /**
+     * Validation/interaction state
+     * @default "default"
+     */
+    state?: FileUploadState;
     /**
      * Whether the upload area is disabled
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Field label rendered above the dropzone
+     */
+    label?: React.ReactNode;
+    /**
+     * Validation error message rendered below the dropzone (styled in danger color)
+     */
+    errorMessage?: React.ReactNode;
     /**
      * Callback when files are selected/dropped
      */

package/dist/components/forms/FormLabel/FormLabel.js

@@ -1,4 +1,4 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { formLabelTheme } from './FormLabel.theme.js';
 import { cn } from '../../../utils/cn.js';
@@ -7,7 +7,7 @@ import { cn } from '../../../utils/cn.js';
  * FormLabel component for providing consistent labeling for form elements
  */
 const FormLabel = React__default.forwardRef(({ htmlFor, children, className, required = false, state = 'default', ...props }, ref) => {
-    return (jsxs("label", { ref: ref, htmlFor: htmlFor, className: cn(formLabelTheme.baseStyle, formLabelTheme.stateStyles[state], className), ...props, children: [children, required && (jsx("span", { className: formLabelTheme.requiredIndicatorStyle, children: "*" }))] }));
+    return (jsxs("label", { ref: ref, htmlFor: htmlFor, className: cn(formLabelTheme.baseStyle, formLabelTheme.stateStyles[state], className), ...props, children: [children, required && (jsxs(Fragment, { children: [jsx("span", { "aria-hidden": "true", className: formLabelTheme.requiredIndicatorStyle, children: "*" }), jsx("span", { className: "sr-only", children: "(required)" })] }))] }));
 });
 FormLabel.displayName = "FormLabel";
 

package/dist/components/forms/Input/Input.js

@@ -62,12 +62,12 @@ const PasswordStrengthIndicator = ({ inline = false, passwordStrengthIndicator,
     const colorClass = strengthConfig.color || "text-neutral-500";
     const label = customLabel || strengthConfig.label || "Password";
     const activeDots = getActiveDots(strength);
-    return (jsxs("div", { className: `${containerStyle} ${indicatorClassName} ${colorClass}`, children: [jsx("div", { className: labelStyle, children: label }), [...Array(5)].map((_, index) => (jsx("div", { className: `${dotStyle} ${index < activeDots ? dotActiveStyle : dotInactiveStyle}` }, index)))] }));
+    return (jsxs("div", { className: `${containerStyle} ${indicatorClassName} ${colorClass}`, children: [jsx("div", { className: labelStyle, children: label }), [...Array(5)].map((_, index) => (jsx("div", { className: `${dotStyle} ${index < activeDots ? dotActiveStyle : dotInactiveStyle}` }, `dot-${index}`)))] }));
 };
 // ============================================================================
 // Main Input Component
 // ============================================================================
-const Input = React__default.forwardRef(({ size = "md", state = "default", className = "", label, labelClassName = "", helperText, helperTextClassName = "", wrapperClassName = "", inputGroupClassName = "", iconStart, iconEnd, contentStart, contentEnd, keyboardShortcut, id, required, type = "text", passwordToggle = type === "password", passwordStrengthIndicator, showNumberControls = false, min, max, step = 1, onChange, onFocus, onBlur, value, currencyDecimalPlaces, darkMode = false, showTypeIcon = true, ...props }, ref) => {
+const Input = React__default.forwardRef(({ size = "md", state = "default", className = "", label, labelClassName = "", helperText, helperTextClassName = "", wrapperClassName = "", inputGroupClassName = "", iconStart, iconEnd, contentStart, contentEnd, keyboardShortcut, id, required, type = "text", passwordToggle = type === "password", passwordStrengthIndicator, showNumberControls = false, min, max, step = 1, onChange, onValueChange, onFocus, onBlur, value, currencyDecimalPlaces, darkMode = false, showTypeIcon = true, ...props }, ref) => {
     const [isFocused, setIsFocused] = useState(false);
     const [showPassword, setShowPassword] = useState(false);
     const generatedId = React__default.useId();
@@ -201,6 +201,7 @@ const Input = React__default.forwardRef(({ size = "md", state = "default", class
             if (onChange) {
                 onChange(event);
             }
+            onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange(newValue.toString());
         }
     };
     // Handle input change
@@ -240,6 +241,7 @@ const Input = React__default.forwardRef(({ size = "md", state = "default", class
         if (onChange) {
             onChange(e);
         }
+        onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange(e.target.value);
     };
     // Theme classes - using simplified approach with design tokens
     const wrapperClasses = inputTheme.wrapperStyle;
@@ -277,7 +279,7 @@ const Input = React__default.forwardRef(({ size = "md", state = "default", class
                                     }, onBlur: (e) => {
                                         setIsFocused(false);
                                         onBlur === null || onBlur === void 0 ? void 0 : onBlur(e);
-                                    }, placeholder: props.placeholder, ...props }), hasLeftIcon && (jsx("div", { className: iconStartClasses, children: finalLeftIcon })), hasRightIcon && !isPasswordField && !displayNumberControls && (jsx("div", { className: iconEndClasses, children: iconEnd })), isPasswordField && (jsx(PasswordToggleButton, { showPassword: showPassword, onToggle: handleTogglePassword, passwordToggleClasses: passwordToggleClasses })), displayNumberControls && (jsx(NumberButtons, { isDisabled: isDisabled, isAtMax: isAtMax, isAtMin: isAtMin, onIncrement: handleIncrement, onDecrement: handleDecrement, numberButtonsContainerClasses: numberButtonsContainerClasses, numberButtonClasses: numberButtonClasses })), hasKeyboardShortcut && (jsx("div", { className: inputTheme.keyboardShortcutStyle, children: keyboardShortcut }))] }), hasContentEnd && (jsx("div", { "data-slot": "content-end", className: cn(contentStyleClasses, contentEndStyle), children: contentEnd }))] }) }), showStrengthBelow && jsx(PasswordStrengthIndicator, { inline: false, passwordStrengthIndicator: passwordStrengthIndicator }), helperText && (typeof helperText === 'string' ? (jsx("div", { id: `${inputId}-helper`, className: cn(helperTextClasses, helperTextClassName), children: helperText })) : (helperText))] }));
+                                    }, placeholder: props.placeholder, ...props }), hasLeftIcon && (jsx("div", { className: iconStartClasses, children: finalLeftIcon })), hasRightIcon && !isPasswordField && !displayNumberControls && (jsx("div", { className: iconEndClasses, children: iconEnd })), isPasswordField && (jsx(PasswordToggleButton, { showPassword: showPassword, onToggle: handleTogglePassword, passwordToggleClasses: passwordToggleClasses })), displayNumberControls && (jsx(NumberButtons, { isDisabled: isDisabled, isAtMax: isAtMax, isAtMin: isAtMin, onIncrement: handleIncrement, onDecrement: handleDecrement, numberButtonsContainerClasses: numberButtonsContainerClasses, numberButtonClasses: numberButtonClasses })), hasKeyboardShortcut && (jsx("div", { className: inputTheme.keyboardShortcutStyle, children: keyboardShortcut }))] }), hasContentEnd && (jsx("div", { "data-slot": "content-end", className: cn(contentStyleClasses, contentEndStyle), children: contentEnd }))] }) }), showStrengthBelow && jsx(PasswordStrengthIndicator, { inline: false, passwordStrengthIndicator: passwordStrengthIndicator }), helperText && (typeof helperText === 'string' ? (jsx("div", { id: `${inputId}-helper`, className: cn(helperTextClasses, helperTextClassName), role: isInvalid ? "alert" : undefined, children: helperText })) : (helperText))] }));
 });
 Input.displayName = "Input";
 

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

@@ -69,6 +69,8 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
      * @default false
      */
     darkMode?: boolean;
+    /** Callback fired with the raw string value on every change — convenience alternative to reading e.target.value from onChange */
+    onValueChange?: (value: string) => void;
 }
 export type InputSize = 'sm' | 'md' | 'lg';
 export type InputState = 'default' | 'disabled' | 'invalid';

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

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

package/dist/components/forms/InputAddress/InputAddress.js

@@ -1,7 +1,6 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default, { useMemo, useState, useCallback } from 'react';
+import React__default, { useMemo, useState, useCallback, useId } from 'react';
 import { Input } from '../Input/Input.js';
-import { FormLabel } from '../FormLabel/FormLabel.js';
 import { inputAddressTheme } from './InputAddress.theme.js';
 
 /**
@@ -21,6 +20,7 @@ import { inputAddressTheme } from './InputAddress.theme.js';
  * ```
  */
 const InputAddress = React__default.forwardRef(({ availableCountries = [], defaultCountry = "United States", onCountryChange, onPostalCodeChange, countryLabel = "Country", postalCodeLabel = "ZIP / Postal code", legendText = "Billing address", streetInputProps = {}, stateInputProps = {}, countryInputProps = {}, postalCodeInputProps = {}, className = "", theme = {}, }, ref) => {
+    var _a;
     // Merge default theme with provided theme using useMemo for performance
     const mergedTheme = useMemo(() => ({
         ...inputAddressTheme,
@@ -56,13 +56,12 @@ const InputAddress = React__default.forwardRef(({ availableCountries = [], defau
         return availableCountries;
     }, [availableCountries]);
     // Create unique IDs for accessibility
-    useMemo(() => `address-fieldset-${Math.random().toString(36).substring(2, 9)}`, []);
-    useMemo(() => `address-legend-${Math.random().toString(36).substring(2, 9)}`, []);
-    const streetId = useMemo(() => `street-${Math.random().toString(36).substring(2, 9)}`, []);
-    const stateId = useMemo(() => `state-${Math.random().toString(36).substring(2, 9)}`, []);
-    const countryId = useMemo(() => `country-${Math.random().toString(36).substring(2, 9)}`, []);
-    const postalCodeId = useMemo(() => `postal-code-${Math.random().toString(36).substring(2, 9)}`, []);
-    return (jsxs("div", { ref: ref, className: `w-full ${className}`, "data-testid": "input-address-fieldset", children: [jsx(FormLabel, { htmlFor: streetId, className: mergedTheme.legendStyles, children: legendText }), jsxs("div", { className: `grid gap-0 ${mergedTheme.contentStyles}`, "data-testid": "input-address-content", children: [jsx("div", { className: "w-full relative focus-within:z-10", "data-testid": "input-address-street", children: jsx(Input, { id: streetId, type: "text", placeholder: "Street address", "aria-label": "street address", inputGroupClassName: "rounded-b-none", ...streetInputProps }) }), jsx("div", { className: "w-full -mt-[0.5px] relative focus-within:z-10", "data-testid": "input-address-state", children: jsx(Input, { id: stateId, type: "text", placeholder: "State", "aria-label": "state", inputGroupClassName: "rounded-none", ...stateInputProps }) }), jsxs("div", { className: "grid grid-cols-1 sm:grid-cols-2 w-full -mt-px relative focus-within:z-10", children: [jsx("div", { className: `${mergedTheme.countryWrapperStyles} w-full sm:pr-0 relative focus-within:z-10`, "data-testid": "input-address-country", children: jsx(Input, { id: countryId, type: "text", value: country, onChange: handleCountryChange, placeholder: countryLabel, "aria-label": countryLabel, inputGroupClassName: "sm:rounded-bl-md rounded-t-none sm:rounded-tr-none sm:rounded-br-none", ...countryInputProps }) }), jsx("div", { className: `${mergedTheme.postalCodeWrapperStyles} w-full relative focus-within:z-10`, "data-testid": "input-address-postal", children: jsx(Input, { id: postalCodeId, type: "text", value: postalCode, onChange: handlePostalCodeChange, placeholder: postalCodeLabel, "aria-label": postalCodeLabel, inputGroupClassName: "sm:rounded-br-md rounded-t-none rounded-tl-none rounded-bl-md sm:rounded-bl-none", ...postalCodeInputProps }) })] })] })] }));
+    const baseId = useId();
+    const streetId = `${baseId}-street`;
+    const stateId = `${baseId}-state`;
+    const countryId = `${baseId}-country`;
+    const postalCodeId = `${baseId}-postal-code`;
+    return (jsxs("fieldset", { ref: ref, className: `w-full border-0 m-0 p-0 ${className}`, "data-testid": "input-address-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-address-content", children: [jsx("div", { className: "w-full relative focus-within:z-10", "data-testid": "input-address-street", children: jsx(Input, { id: streetId, type: "text", placeholder: "Street address", "aria-label": "street address", inputGroupClassName: "rounded-b-none", ...streetInputProps }) }), jsx("div", { className: "w-full -mt-[0.5px] relative focus-within:z-10", "data-testid": "input-address-state", children: jsx(Input, { id: stateId, type: "text", placeholder: "State", "aria-label": "state", inputGroupClassName: "rounded-none", ...stateInputProps }) }), jsxs("div", { className: "grid grid-cols-1 sm:grid-cols-2 w-full -mt-px relative focus-within:z-10", children: [jsx("div", { className: `${mergedTheme.countryWrapperStyles} w-full sm:pr-0 relative focus-within:z-10`, "data-testid": "input-address-country", children: jsx(Input, { id: countryId, type: "text", value: country, onChange: handleCountryChange, placeholder: countryLabel, "aria-label": countryLabel, inputGroupClassName: "sm:rounded-bl-md rounded-t-none sm:rounded-tr-none sm:rounded-br-none", ...countryInputProps }) }), jsx("div", { className: `${mergedTheme.postalCodeWrapperStyles} w-full relative focus-within:z-10`, "data-testid": "input-address-postal", children: jsx(Input, { id: postalCodeId, type: "text", value: postalCode, onChange: handlePostalCodeChange, placeholder: postalCodeLabel, "aria-label": postalCodeLabel, inputGroupClassName: "sm:rounded-br-md rounded-t-none rounded-tl-none rounded-bl-md sm:rounded-bl-none", ...postalCodeInputProps }) })] })] })] }));
 });
 InputAddress.displayName = "InputAddress";
 

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;
     /**