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

package/dist/components/forms/FileUpload/FileUploadProgress.js

@@ -0,0 +1,119 @@
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
+import React__default, { useState, useEffect } from 'react';
+import { useReducedMotion, motion, AnimatePresence } from 'motion/react';
+import { File, Trash, ArrowsClockwise, X, Check } from '@phosphor-icons/react';
+import { Icon } from '../../core/Icon/Icon.js';
+import { fileTypes } from '../../core/Icon/data/fileTypes.js';
+import { cn } from '../../../utils/cn.js';
+import { getFileExtension, formatFileSize } from '../../../utils/formatUtils.js';
+import { Popover } from '../../core/Popover/Popover.js';
+import '../../core/Popover/PopoverContext.js';
+import '../../core/Popover/PopoverBody.js';
+import { Button } from '../../core/Button/Button.js';
+import { fileUploadProgressTheme } from './FileUploadProgress.theme.js';
+import { REMOVE_BUTTON_ENTER, PROGRESS_SPRING, CROSSFADE } from './FileUploadProgress.animations.js';
+
+const isKnownFileType = (ext) => {
+    return ext in fileTypes;
+};
+// SVG viewBox is 36×36 — small enough for crisp rendering, large enough for smooth arcs
+const VIEWBOX = 36;
+const CENTER = VIEWBOX / 2;
+const RadialProgress = ({ progress, status, strokeWidth, trackColor, progressColor, centerTextStyle, statusIconColor, sizeClass, shouldReduceMotion, confirmRemove, completionDelay, onRemove, onRetry, }) => {
+    const [isHovered, setIsHovered] = useState(false);
+    const [confirmOpen, setConfirmOpen] = useState(false);
+    const [showRemove, setShowRemove] = useState(false);
+    const radius = (VIEWBOX - strokeWidth) / 2;
+    const circumference = 2 * Math.PI * radius;
+    const offset = circumference * (1 - progress / 100);
+    const isUploading = status === "uploading";
+    const isComplete = status === "complete";
+    const isError = status === "error";
+    // After completing, show tick briefly then transition to remove button
+    useEffect(() => {
+        if (isComplete) {
+            setShowRemove(false);
+            const timer = setTimeout(() => setShowRemove(true), completionDelay);
+            return () => clearTimeout(timer);
+        }
+        setShowRemove(false);
+    }, [isComplete, completionDelay]);
+    const handleClick = () => {
+        if (!onRemove)
+            return;
+        if (confirmRemove) {
+            setConfirmOpen(true);
+        }
+        else {
+            onRemove();
+        }
+    };
+    const handleConfirm = () => {
+        setConfirmOpen(false);
+        onRemove === null || onRemove === void 0 ? void 0 : onRemove();
+    };
+    // Uploading/complete: the radial doubles as the cancel/remove target.
+    const isClickable = !!onRemove;
+    const ariaLabel = onRemove ? "Remove file" : undefined;
+    // Confirm popover shared by the radial (cancel/remove) and the error-state delete button.
+    const confirmPopover = (trigger, label, offsetValue) => (jsxs(Popover, { isOpen: confirmOpen, onOpenChange: (open) => {
+            setConfirmOpen(open);
+            if (!open)
+                setIsHovered(false);
+        }, placement: "bottom-end", offset: offsetValue, triggerType: "click", children: [jsx(Popover.Trigger, { children: trigger }), jsxs(Popover.Body, { className: "flex items-center p-1 border-[0.5px] rounded-xl gap-0.5 bg-opacity-50 backdrop-blur-md", children: [jsx("span", { className: "text-sm font-semibold text-[var(--color-text-secondary)] px-3", children: label }), jsxs("div", { className: "flex gap-1", children: [jsx(Button, { size: "sm", color: "danger", variant: "filled", onClick: handleConfirm, children: "Yesss" }), jsx(Button, { size: "sm", variant: "soft", color: "mono", onClick: () => setConfirmOpen(false), children: "No" })] })] })] }));
+    // Shared remove button used after completion tick
+    const removeButton = (jsx(motion.div, { initial: shouldReduceMotion ? false : REMOVE_BUTTON_ENTER.initial, animate: REMOVE_BUTTON_ENTER.animate, transition: REMOVE_BUTTON_ENTER.transition, className: "shrink-0", children: jsx(Button, { size: "sm", variant: "soft", color: "mono", "aria-label": "Remove file", iconOnly: true, className: "rounded-full size-8", onClick: confirmRemove ? undefined : () => onRemove === null || onRemove === void 0 ? void 0 : onRemove(), children: jsx(Trash, { className: "size-3.5", weight: "bold" }) }) }, "remove-btn"));
+    // Error state: retry + delete buttons (no progress arc/percentage).
+    if (isError) {
+        const deleteButton = onRemove ? (jsx(Button, { size: "sm", variant: "soft", color: "mono", "aria-label": "Remove file", iconOnly: true, className: "rounded-full size-8", onClick: confirmRemove ? undefined : () => onRemove(), children: jsx(Trash, { className: "size-3.5", weight: "bold" }) })) : null;
+        return (jsxs("div", { className: "flex items-center gap-1 shrink-0", children: [onRetry && (jsx(Button, { size: "sm", variant: "soft", color: "mono", "aria-label": "Retry upload", iconOnly: true, className: "rounded-full size-8", onClick: () => onRetry(), children: jsx(ArrowsClockwise, { className: "size-3.5", weight: "bold" }) })), deleteButton &&
+                    (confirmRemove
+                        ? confirmPopover(deleteButton, "Remove file?", 6)
+                        : deleteButton)] }));
+    }
+    const radialElement = (jsxs("div", { className: cn("relative shrink-0", sizeClass, isClickable && "cursor-pointer"), onMouseEnter: () => setIsHovered(true), onMouseLeave: () => {
+            if (!confirmOpen)
+                setIsHovered(false);
+        }, onClick: isClickable ? handleClick : undefined, role: isClickable ? "button" : undefined, tabIndex: isClickable ? 0 : undefined, "aria-label": ariaLabel, onKeyDown: isClickable
+            ? (e) => {
+                if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault();
+                    handleClick();
+                }
+            }
+            : undefined, children: [jsxs("svg", { viewBox: `0 0 ${VIEWBOX} ${VIEWBOX}`, className: "w-full h-full -rotate-90", children: [jsx("circle", { cx: CENTER, cy: CENTER, r: radius, fill: "none", stroke: trackColor, strokeWidth: strokeWidth }), jsx(motion.circle, { cx: CENTER, cy: CENTER, r: radius, fill: "none", stroke: progressColor, strokeWidth: strokeWidth, strokeLinecap: "round", strokeDasharray: circumference, initial: { strokeDashoffset: circumference }, animate: { strokeDashoffset: isComplete ? 0 : offset }, transition: shouldReduceMotion ? { duration: 0 } : PROGRESS_SPRING })] }), jsx("div", { className: "absolute inset-0 flex items-center justify-center", children: jsxs(AnimatePresence, { mode: "wait", initial: false, children: [isUploading && !isHovered && (jsx(motion.span, { className: centerTextStyle, ...(shouldReduceMotion ? {} : CROSSFADE), children: progress }, "percent")), isUploading && isHovered && onRemove && (jsx(motion.span, { ...(shouldReduceMotion ? {} : CROSSFADE), children: jsx(X, { className: "size-4 text-[var(--color-text-muted)]", weight: "bold" }) }, "close")), isComplete && !showRemove && (jsx(motion.span, { ...(shouldReduceMotion ? {} : CROSSFADE), children: jsx(Check, { className: cn("size-4", statusIconColor), weight: "bold" }) }, "check"))] }) })] }));
+    // Determine what to render: radial indicator or remove button
+    const showRemoveButton = isComplete && showRemove && onRemove;
+    const triggerElement = showRemoveButton ? removeButton : radialElement;
+    // No confirm popover needed — return the element directly.
+    if (!confirmRemove || !onRemove)
+        return triggerElement;
+    return confirmPopover(triggerElement, isComplete ? "Remove file?" : "Cancel upload?", isComplete ? 2 : 6);
+};
+// --- Main Component ---
+const FileUploadProgress = React__default.forwardRef(({ items, onRemove, onRetry, showFileSize = true, confirmRemove = true, completionDelay = 1500, className, theme: themeOverrides, ...rest }, ref) => {
+    var _a;
+    const shouldReduceMotion = useReducedMotion();
+    const t = fileUploadProgressTheme;
+    if (items.length === 0)
+        return null;
+    const radialProgressColors = {
+        ...t.radialProgressColors,
+        ...themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.radialProgressColors,
+    };
+    const statusIconColors = {
+        ...t.statusIconColors,
+        ...themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.statusIconColors,
+    };
+    return (jsx("div", { ref: ref, className: cn((_a = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.containerStyle) !== null && _a !== void 0 ? _a : t.containerStyle, className), ...rest, children: items.map((item) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+            const clampedProgress = Math.min(100, Math.max(0, item.progress));
+            const ext = getFileExtension(item.file.name);
+            const hasFileTypeIcon = ext !== null && isKnownFileType(ext);
+            return (jsxs("div", { className: (_a = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.itemStyle) !== null && _a !== void 0 ? _a : t.itemStyle, children: [hasFileTypeIcon ? (jsx("span", { className: "shrink-0", children: jsx(Icon, { icon: ext, size: "lg" }) })) : (jsx("span", { className: cn((_b = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.iconContainerStyle) !== null && _b !== void 0 ? _b : t.iconContainerStyle, t.iconSize), children: jsx(File, { className: (_c = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.iconStyle) !== null && _c !== void 0 ? _c : t.iconStyle }) })), jsxs("div", { className: (_d = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.fileInfoStyle) !== null && _d !== void 0 ? _d : t.fileInfoStyle, children: [jsx("p", { className: (_e = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.fileNameStyle) !== null && _e !== void 0 ? _e : t.fileNameStyle, children: item.file.name }), item.status === "error" && item.error ? (jsx("p", { className: (_f = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.errorTextStyle) !== null && _f !== void 0 ? _f : t.errorTextStyle, children: item.error })) : (showFileSize && (jsx("p", { className: (_g = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.fileSizeStyle) !== null && _g !== void 0 ? _g : t.fileSizeStyle, children: formatFileSize(item.file.size) })))] }), jsx(RadialProgress, { progress: clampedProgress, status: item.status, strokeWidth: t.radialStroke, trackColor: (_h = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.radialTrackColor) !== null && _h !== void 0 ? _h : t.radialTrackColor, progressColor: radialProgressColors[item.status], centerTextStyle: (_j = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.radialCenterTextStyle) !== null && _j !== void 0 ? _j : t.radialCenterTextStyle, statusIconColor: statusIconColors[item.status], sizeClass: t.radialSize, shouldReduceMotion: shouldReduceMotion, confirmRemove: confirmRemove, completionDelay: completionDelay, onRemove: onRemove ? () => onRemove(item.id) : undefined, onRetry: onRetry ? () => onRetry(item.id) : undefined })] }, item.id));
+        }) }));
+});
+FileUploadProgress.displayName = "FileUploadProgress";
+
+export { FileUploadProgress };

package/dist/components/forms/FileUpload/FileUploadProgress.theme.d.ts

@@ -0,0 +1,19 @@
+import type { FileUploadProgressStatus } from "./FileUploadProgress.types";
+export interface FileUploadProgressTheme {
+    containerStyle: string;
+    itemStyle: string;
+    iconContainerStyle: string;
+    iconStyle: string;
+    fileInfoStyle: string;
+    fileNameStyle: string;
+    fileSizeStyle: string;
+    radialTrackColor: string;
+    radialProgressColors: Record<FileUploadProgressStatus, string>;
+    radialCenterTextStyle: string;
+    statusIconColors: Record<FileUploadProgressStatus, string>;
+    errorTextStyle: string;
+    radialSize: string;
+    radialStroke: number;
+    iconSize: string;
+}
+export declare const fileUploadProgressTheme: FileUploadProgressTheme;

package/dist/components/forms/FileUpload/FileUploadProgress.theme.js

@@ -0,0 +1,27 @@
+const fileUploadProgressTheme = {
+    containerStyle: "flex flex-col gap-3",
+    itemStyle: "w-full flex items-center gap-x-3",
+    iconContainerStyle: "flex items-center justify-center rounded-lg shrink-0 border border-[var(--color-border)] bg-[var(--color-background-secondary)]",
+    iconStyle: "shrink-0 size-5 text-[var(--color-text-muted)]",
+    fileInfoStyle: "flex-1 min-w-0",
+    fileNameStyle: "text-sm font-medium text-[var(--color-text-primary)] truncate",
+    fileSizeStyle: "text-xs text-[var(--color-text-muted)]",
+    radialTrackColor: "var(--color-surface-sunken)",
+    radialProgressColors: {
+        uploading: "var(--color-primary)",
+        complete: "var(--color-success)",
+        error: "var(--color-danger)",
+    },
+    radialCenterTextStyle: "text-xs tracking-tight font-semibold tabular-nums text-[var(--color-text-secondary)]",
+    statusIconColors: {
+        uploading: "",
+        complete: "text-[var(--color-success)]",
+        error: "text-[var(--color-danger)]",
+    },
+    errorTextStyle: "text-xs text-[var(--color-danger)]",
+    iconSize: "size-10",
+    radialSize: "size-8",
+    radialStroke: 3,
+};
+
+export { fileUploadProgressTheme };

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

@@ -0,0 +1,33 @@
+export type FileUploadProgressStatus = 'uploading' | 'complete' | 'error';
+export interface FileUploadProgressItem {
+    id: string;
+    file: File;
+    progress: number;
+    status: FileUploadProgressStatus;
+    error?: string;
+}
+export interface FileUploadProgressThemeOverrides {
+    containerStyle?: string;
+    itemStyle?: string;
+    iconContainerStyle?: string;
+    iconStyle?: string;
+    fileInfoStyle?: string;
+    fileNameStyle?: string;
+    fileSizeStyle?: string;
+    radialTrackColor?: string;
+    radialProgressColors?: Partial<Record<FileUploadProgressStatus, string>>;
+    radialCenterTextStyle?: string;
+    statusIconColors?: Partial<Record<FileUploadProgressStatus, string>>;
+    errorTextStyle?: string;
+}
+export interface FileUploadProgressProps extends React.HTMLAttributes<HTMLDivElement> {
+    items: FileUploadProgressItem[];
+    onRemove?: (id: string) => void;
+    onRetry?: (id: string) => void;
+    showFileSize?: boolean;
+    confirmRemove?: boolean;
+    /** Delay in ms before the completion tick transitions to the remove button. Default: 1500 */
+    completionDelay?: number;
+    className?: string;
+    theme?: FileUploadProgressThemeOverrides;
+}

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

@@ -1,3 +1,6 @@
 export { FileUpload } from './FileUpload';
 export { fileUploadTheme } from './FileUpload.theme';
 export type { FileUploadProps, FileUploadError, FileUploadThemeOverrides, UploadedFile } from './FileUpload.types';
+export { FileUploadProgress } from './FileUploadProgress';
+export { fileUploadProgressTheme } from './FileUploadProgress.theme';
+export type { FileUploadProgressProps, FileUploadProgressItem, FileUploadProgressStatus, FileUploadProgressThemeOverrides, } from './FileUploadProgress.types';

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/FormLabel/FormLabel.theme.js

@@ -3,7 +3,7 @@
  */
 const formLabelTheme = {
     // Base styles for the label element
-    baseStyle: "block text-sm/6 font-medium mb-2",
+    baseStyle: "block text-sm/6 font-medium mb-1",
     // State variants - using design tokens from global.scss
     stateStyles: {
         default: "text-[var(--color-text-primary)]",

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

@@ -1,15 +1,10 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useState, useRef, useEffect, useCallback } from 'react';
 import { FormLabel } from '../FormLabel/FormLabel.js';
 import { inputTheme } from './Input.theme.js';
 import { cn } from '../../../utils/cn.js';
-import { LockClosedIcon, EyeSlashIcon, EyeIcon } from '@heroicons/react/24/solid';
-import { PlusIcon } from '../../../icons/core/PlusIcon.js';
-import { MinusIcon } from '../../../icons/core/MinusIcon.js';
-import { SearchIcon } from '../../../icons/core/SearchIcon.js';
-import '../../../icons/core/LockIcon.js';
-import '../../../icons/core/DollarIcon.js';
-import '../../../icons/core/TickIcon.js';
+import { Lock, MagnifyingGlass, EyeSlash, Eye, Minus, Plus } from '@phosphor-icons/react';
 import { validateMaskedInput, applyInputMask, getAdjustedCursorPosition } from './inputMasks.js';
 
 const PasswordToggleButton = ({ showPassword, onToggle, passwordToggleClasses, }) => {
@@ -23,7 +18,7 @@ const PasswordToggleButton = ({ showPassword, onToggle, passwordToggleClasses, }
                 e.preventDefault();
                 onToggle();
             }
-        }, children: showPassword ? (jsx(EyeSlashIcon, { className: toggleIconActive, "aria-hidden": "true" })) : (jsx(EyeIcon, { className: toggleIconInactive, "aria-hidden": "true" })) }));
+        }, children: showPassword ? (jsx(EyeSlash, { className: toggleIconActive, "aria-hidden": "true" })) : (jsx(Eye, { className: toggleIconInactive, "aria-hidden": "true" })) }));
 };
 const NumberButtons = ({ isDisabled, isAtMax, isAtMin, onIncrement, onDecrement, numberButtonsContainerClasses, numberButtonClasses, }) => {
     const incrementIconStyle = inputTheme.typeStyles.number.incrementIconStyle;
@@ -31,10 +26,10 @@ const NumberButtons = ({ isDisabled, isAtMax, isAtMin, onIncrement, onDecrement,
     return (jsxs("div", { className: numberButtonsContainerClasses, children: [jsx("button", { type: "button", className: `${numberButtonClasses}`, onClick: (e) => {
                     e.stopPropagation();
                     onDecrement();
-                }, disabled: isDisabled || isAtMin, "aria-label": "Decrease value", tabIndex: -1, children: jsx(MinusIcon, { size: "xs", className: decrementIconStyle, "aria-hidden": "true" }) }), jsx("button", { type: "button", className: `${numberButtonClasses}`, onClick: (e) => {
+                }, disabled: isDisabled || isAtMin, "aria-label": "Decrease value", tabIndex: -1, children: jsx(Minus, { className: cn("size-4", decrementIconStyle), "aria-hidden": "true" }) }), jsx("button", { type: "button", className: `${numberButtonClasses}`, onClick: (e) => {
                     e.stopPropagation();
                     onIncrement();
-                }, disabled: isDisabled || isAtMax, "aria-label": "Increase value", tabIndex: -1, children: jsx(PlusIcon, { size: "xs", className: incrementIconStyle, "aria-hidden": "true" }) })] }));
+                }, disabled: isDisabled || isAtMax, "aria-label": "Increase value", tabIndex: -1, children: jsx(Plus, { className: cn("size-4", incrementIconStyle), "aria-hidden": "true" }) })] }));
 };
 const getActiveDots = (strength) => {
     switch (strength) {
@@ -67,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, ...props }, ref) => {
+const Input = React__default.forwardRef(({ size = "md", state = "default", className = "", label, labelClassName = "", helperText, errorMessage, 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();
@@ -87,14 +82,17 @@ const Input = React__default.forwardRef(({ size = "md", state = "default", class
     const inputRef = useRef(null);
     const cursorPositionRef = useRef(null);
     // Default icons based on input type
-    const defaultPasswordIcon = type === "password" && !iconStart ? (jsx(LockClosedIcon, { className: "size-5 text-[var(--color-text-muted)]" })) : null;
-    const defaultSearchIcon = type === "search" && !iconStart ? (jsx(SearchIcon, { size: "sm", className: inputTheme.typeStyles.search.iconStyle })) : null;
+    const defaultPasswordIcon = showTypeIcon && type === "password" && !iconStart ? (jsx(Lock, { className: "size-5 text-[var(--color-text-muted)]" })) : null;
+    const defaultSearchIcon = showTypeIcon && type === "search" && !iconStart ? (jsx(MagnifyingGlass, { className: cn("size-5", inputTheme.typeStyles.search.iconStyle) })) : null;
     // Use the provided iconStart or the default icon based on input type
     const finalLeftIcon = iconStart || defaultPasswordIcon || defaultSearchIcon;
     // Derived state flags for internal use
     const hasLeftIcon = Boolean(finalLeftIcon);
     const isDisabled = state === "disabled";
     const isInvalid = state === "invalid";
+    // errorMessage takes precedence over helperText while invalid; helperText
+    // behavior is unchanged otherwise.
+    const displayedMessage = isInvalid && errorMessage ? errorMessage : helperText;
     const hasRightIcon = Boolean(iconEnd);
     const hasContentStart = Boolean(contentStart);
     const hasContentEnd = Boolean(contentEnd);
@@ -206,6 +204,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
@@ -245,6 +244,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;
@@ -275,14 +275,14 @@ const Input = React__default.forwardRef(({ size = "md", state = "default", class
         numberValue !== undefined &&
         typeof min === "number" &&
         numberValue <= min;
-    return (jsxs("div", { className: cn(wrapperClasses, stateClass, wrapperClassName), children: [label && (jsxs("div", { className: "flex justify-between items-center", children: [jsx(FormLabel, { htmlFor: inputId, className: labelClassName, state: state, required: required, children: label }), showStrengthWithLabel && (jsx(PasswordStrengthIndicator, { inline: true, passwordStrengthIndicator: passwordStrengthIndicator }))] })), jsx("div", { children: jsxs("div", { className: cn(inputGroupClasses, stateClasses, isFocused && (isInvalid ? inputTheme.inputGroupFocusInvalidStyle : inputTheme.inputGroupFocusStyle), inputGroupClassName), onClick: handleInputGroupClick, role: "presentation", children: [hasContentStart && (jsx("div", { "data-slot": "content-start", className: cn(contentStyleClasses, contentStartStyle), children: contentStart })), jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: setInputRef, id: inputId, type: actualInputType, className: cn(baseClasses, sizeClasses, hasLeftIcon && iconStartPadding, (hasRightIcon || isPasswordField || displayNumberControls) &&
-                                        iconEndPadding, className), disabled: isDisabled, "aria-invalid": isInvalid, required: required, min: min, max: max, step: step, value: value, onChange: handleInputChange, onFocus: (e) => {
+    return (jsxs("div", { className: cn(wrapperClasses, stateClass, darkMode && "dark", wrapperClassName), children: [label && (typeof label === 'string' ? (jsxs("div", { className: "flex justify-between items-center", children: [jsx(FormLabel, { htmlFor: inputId, className: labelClassName, state: state, required: required, children: label }), showStrengthWithLabel && (jsx(PasswordStrengthIndicator, { inline: true, passwordStrengthIndicator: passwordStrengthIndicator }))] })) : (jsxs("div", { className: "flex justify-between items-center", children: [label, showStrengthWithLabel && (jsx(PasswordStrengthIndicator, { inline: true, passwordStrengthIndicator: passwordStrengthIndicator }))] }))), jsx("div", { children: jsxs("div", { className: cn(inputGroupClasses, stateClasses, isFocused && (isInvalid ? inputTheme.inputGroupFocusInvalidStyle : inputTheme.inputGroupFocusStyle), inputGroupClassName), onClick: handleInputGroupClick, role: "presentation", children: [hasContentStart && (jsx("div", { "data-slot": "content-start", className: cn(contentStyleClasses, contentStartStyle), children: contentStart })), jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: setInputRef, id: inputId, type: actualInputType, className: cn(baseClasses, sizeClasses, hasLeftIcon && iconStartPadding, (hasRightIcon || isPasswordField || displayNumberControls) &&
+                                        iconEndPadding, className), disabled: isDisabled, "aria-invalid": isInvalid, "aria-describedby": displayedMessage ? `${inputId}-helper` : undefined, required: required, min: min, max: max, step: step, value: value, onChange: handleInputChange, onFocus: (e) => {
                                         setIsFocused(true);
                                         onFocus === null || onFocus === void 0 ? void 0 : onFocus(e);
                                     }, 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 && (jsx("div", { className: cn(helperTextClasses, helperTextClassName), children: 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 }), displayedMessage && (typeof displayedMessage === 'string' ? (jsx("div", { id: `${inputId}-helper`, className: cn(helperTextClasses, helperTextClassName), role: isInvalid ? "alert" : undefined, children: displayedMessage })) : (displayedMessage))] }));
 });
 Input.displayName = "Input";
 

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

@@ -8,17 +8,17 @@ const inputTheme = {
     // Base container styles
     wrapperStyle: formsBaseTheme.wrapperStyle,
     // Input group styles - no focus-within (focus is managed via JS for contentStart/contentEnd compatibility)
-    inputGroupStyle: "relative flex rounded-[var(--form-radius)] outline outline-1 outline-[var(--color-border)] " +
-        "bg-white transition-all " +
-        "dark:bg-[var(--color-neutral-900)] dark:outline-[var(--color-neutral-700)]",
+    inputGroupStyle: "relative flex rounded-[var(--form-radius)] shadow-[inset_0_0_0_1px_var(--color-border)] " +
+        "bg-[var(--field-fill)] transition-all " +
+        // Hover edge: strengthen the border to --color-border-secondary on hover. Scoped with
+        // not-focus-within so the JS-driven focus border (primary) always wins.
+        "not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-border-secondary)]",
     // JS-driven focus ring (applied when isFocused is true)
-    inputGroupFocusStyle: "outline-2 outline-[var(--color-primary-600)] -outline-offset-1 " +
-        "ring-4 ring-[var(--color-primary)]/10 " +
-        "dark:outline-[var(--color-primary-500)] dark:ring-[var(--color-primary-500)]/20",
+    inputGroupFocusStyle: "shadow-[inset_0_0_0_1px_var(--color-primary-600)] ring-4 ring-[var(--color-primary)]/10 " +
+        "dark:shadow-[inset_0_0_0_1px_var(--color-primary-500)] dark:ring-[var(--color-primary-500)]/20",
     // JS-driven focus ring for invalid state
-    inputGroupFocusInvalidStyle: "outline-2 outline-[var(--color-danger)] -outline-offset-1 " +
-        "ring-4 ring-[var(--color-danger)]/10 " +
-        "dark:outline-[var(--color-danger-500)] dark:ring-[var(--color-danger-500)]/20",
+    inputGroupFocusInvalidStyle: "shadow-[inset_0_0_0_1px_var(--color-danger)] ring-4 ring-[var(--color-danger)]/10 " +
+        "dark:shadow-[inset_0_0_0_1px_var(--color-danger-500)] dark:ring-[var(--color-danger-500)]/20",
     // Base input styles - extends common form control with design tokens
     baseStyle: `${formsBaseTheme.controlBaseStyle} py-2 px-3`,
     // Size variants - composed from atomic tokens
@@ -31,8 +31,14 @@ const inputTheme = {
     states: {
         default: formsBaseTheme.states.default,
         disabled: formsBaseTheme.states.disabled,
-        invalid: "outline-[var(--color-danger)] bg-[var(--color-danger-50)] " +
-            "dark:bg-[var(--color-danger-950)]/30 dark:outline-[var(--color-danger-500)]",
+        // Invalid = danger border + faint danger ring, NO surface fill (matches formsBaseTheme
+        // and the composite overlay). Focus is JS-driven via inputGroupFocusInvalidStyle, so no
+        // focus-within ring override is needed here.
+        invalid: "shadow-[inset_0_0_0_1px_var(--color-danger)] ring-4 ring-[var(--color-danger)]/10 " +
+            // Keep the danger border on hover (don't let the hover edge override it)
+            "not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-danger)] " +
+            "dark:shadow-[inset_0_0_0_1px_var(--color-danger-500)] dark:ring-[var(--color-danger-500)]/20 " +
+            "dark:not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-danger-500)]",
     },
     // Helper text styles with state handling
     helperText: formsBaseTheme.helperText,
@@ -43,46 +49,51 @@ const inputTheme = {
     iconPadding: formsBaseTheme.iconStyles.padding,
     // Content styles - prefix/suffix content with size-aware font sizes
     contentStyle: {
-        sm: `flex items-center px-3 ${formsBaseTheme.sizes.sm.text} text-[var(--color-text-muted)] shrink-0 dark:text-[var(--color-neutral-500)]`,
-        md: `flex items-center px-3 ${formsBaseTheme.sizes.md.text} text-[var(--color-text-muted)] shrink-0 dark:text-[var(--color-neutral-500)]`,
-        lg: `flex items-center px-3 ${formsBaseTheme.sizes.lg.text} text-[var(--color-text-muted)] shrink-0 dark:text-[var(--color-neutral-500)]`,
+        sm: `flex items-center px-3 ${formsBaseTheme.sizes.sm.text} text-[var(--color-text-muted)] shrink-0`,
+        md: `flex items-center px-3 ${formsBaseTheme.sizes.md.text} text-[var(--color-text-muted)] shrink-0`,
+        lg: `flex items-center px-3 ${formsBaseTheme.sizes.lg.text} text-[var(--color-text-muted)] shrink-0`,
     },
     contentStartStyle: "pr-0 " +
         "[&:has([aria-haspopup])]:pl-0 " +
-        "[&_[aria-haspopup]]:outline-none [&_[aria-haspopup]]:ring-0 [&_[aria-haspopup]]:shadow-none " +
+        // ! important so these beat the nested Select button's own hover:/focus-within: edge+ring
+        // rules (those carry extra pseudo-class specificity); !shadow-none also clears the ring,
+        // which Tailwind renders via box-shadow.
+        "[&_[aria-haspopup]]:outline-none [&_[aria-haspopup]]:!ring-0 [&_[aria-haspopup]]:!shadow-none " +
         "[&_[aria-haspopup]]:border-none [&_[aria-haspopup]]:rounded-none [&_[aria-haspopup]]:bg-transparent " +
         "[&_[aria-haspopup]]:min-h-0 [&_[aria-haspopup]]:h-full",
     contentEndStyle: "pl-0 " +
         "[&:has([aria-haspopup])]:pr-0 " +
-        "[&_[aria-haspopup]]:outline-none [&_[aria-haspopup]]:ring-0 [&_[aria-haspopup]]:shadow-none " +
+        "[&_[aria-haspopup]]:outline-none [&_[aria-haspopup]]:!ring-0 [&_[aria-haspopup]]:!shadow-none " +
         "[&_[aria-haspopup]]:border-none [&_[aria-haspopup]]:rounded-none [&_[aria-haspopup]]:bg-transparent " +
         "[&_[aria-haspopup]]:min-h-0 [&_[aria-haspopup]]:h-full",
     // Keyboard shortcut display
-    keyboardShortcutStyle: "absolute inset-y-0 right-0 flex items-center pr-3 text-[var(--color-text-muted)] z-10 " +
-        "dark:text-[var(--color-neutral-500)]",
+    keyboardShortcutStyle: "absolute inset-y-0 right-0 flex items-center pr-3 text-[var(--color-text-muted)] z-10",
     // Password toggle button with hover states
     passwordToggleStyle: "absolute inset-y-0 right-0 flex items-center pr-3 cursor-pointer " +
-        "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors z-10 " +
-        "dark:text-[var(--color-neutral-500)] dark:hover:text-[var(--color-neutral-200)]",
+        "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors z-10",
     // Number input controls
     numberButtonsContainerStyle: "absolute inset-y-0 right-0 flex flex-row items-center pr-2 z-10 gap-1",
-    numberButtonStyle: "bg-[var(--color-background-secondary)] flex items-center justify-center " +
-        "text-[var(--color-text-muted)] hover:bg-[var(--color-background-tertiary)] " +
-        "hover:text-[var(--color-text-primary)] cursor-pointer size-6 rounded-sm transition-colors " +
-        "dark:bg-[var(--color-neutral-800)] dark:text-[var(--color-neutral-500)] " +
-        "dark:hover:bg-[var(--color-neutral-700)] dark:hover:text-[var(--color-neutral-200)]",
+    // In-field micro-affordance (like the password toggle) — deliberately a plain
+    // <button>, NOT the Button component (form-control heights don't fit in the
+    // field). --checkbox-radius = the capped small-control radius, so it follows
+    // --radius-base without going full pill at 24px.
+    numberButtonStyle: "bg-[var(--color-surface-sunken)] flex items-center justify-center " +
+        "text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] " +
+        "hover:text-[var(--color-text-primary)] cursor-pointer size-6 rounded-[var(--checkbox-radius)] transition-colors " +
+        "outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] " +
+        "disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-[var(--color-surface-sunken)]",
     // Type-specific styles organized by input type
     typeStyles: {
         password: {
-            toggleIconActive: "size-5 text-[var(--color-text-primary)] dark:text-[var(--color-neutral-200)]",
-            toggleIconInactive: "size-5 text-[var(--color-text-muted)] dark:text-[var(--color-neutral-500)]",
+            toggleIconActive: "size-5 text-[var(--color-text-primary)]",
+            toggleIconInactive: "size-5 text-[var(--color-text-muted)]",
         },
         search: {
-            iconStyle: "text-[var(--color-text-muted)] dark:text-[var(--color-neutral-500)]",
+            iconStyle: "text-[var(--color-text-muted)]",
         },
         number: {
-            incrementIconStyle: "text-[var(--color-text-muted)] dark:text-[var(--color-neutral-500)]",
-            decrementIconStyle: "text-[var(--color-text-muted)] dark:text-[var(--color-neutral-500)]",
+            incrementIconStyle: "text-[var(--color-text-muted)]",
+            decrementIconStyle: "text-[var(--color-text-muted)]",
         },
     },
     // Password strength indicator with design tokens
@@ -91,7 +102,7 @@ const inputTheme = {
         labelStyle: "text-xs font-semibold mr-1",
         dotStyle: "size-1.5 rounded-full",
         dotActiveStyle: "bg-current",
-        dotInactiveStyle: "bg-[var(--color-border)] dark:bg-[var(--color-neutral-700)]",
+        dotInactiveStyle: "bg-[var(--color-border)] dark:bg-[var(--color-mono-700)]",
         strengthStyles: {
             weak: {
                 label: "Weak",

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

@@ -27,10 +27,16 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
      * supports masked input types: 'creditCard', 'expiryDate', 'phone', 'ssn', 'currency'
      */
     type?: InputType;
-    /** Optional label text for the input */
-    label?: string;
-    /** Optional helper text displayed below the input */
-    helperText?: string;
+    /** Optional label for the input — pass a string for default styling, or a ReactNode for full control */
+    label?: React.ReactNode;
+    /** Optional helper text below the input — pass a string for default styling, or a ReactNode for full control */
+    helperText?: React.ReactNode;
+    /**
+     * Error message shown instead of `helperText` when `state="invalid"`.
+     * Takes precedence over `helperText` while invalid; `helperText` is
+     * unaffected/still shown as normal otherwise.
+     */
+    errorMessage?: React.ReactNode;
     /** Icon to display before the input (small decorative) */
     iconStart?: React.ReactNode;
     /** Icon to display after the input (small decorative) */
@@ -61,6 +67,16 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
     passwordStrengthIndicator?: PasswordStrengthIndicator;
     /** Number of decimal places for currency inputs (default: 2). Only applies when type="currency" */
     currencyDecimalPlaces?: number;
+    /** Whether to show the automatic type-based icon (lock for password, magnifier for search). Default: true */
+    showTypeIcon?: boolean;
+    /**
+     * Force dark mode styling for the component. Use when placing the component
+     * on a dark background while the page is in light mode.
+     * @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/Input/index.d.ts

@@ -1,3 +1,4 @@
 export { Input } from './Input';
 export type { InputProps, InputSize, InputState, InputTheme, InputType, PasswordStrength, PasswordStrengthIndicator } from './Input.types';
 export { inputTheme } from './Input.theme';
+export { isValidExpiryDate, isValidMonth } from './inputMasks';

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

@@ -20,6 +20,30 @@ export declare const formatExpiryDate: (value: string) => string;
  * @returns Whether the month is valid
  */
 export declare const isValidMonth: (value: string) => boolean;
+/**
+ * Validate a complete card expiry date (MM/YY): the month must be 01-12 AND the date
+ * must not be in the past. A card is considered valid through the LAST day of its expiry
+ * month, so the current month still passes.
+ *
+ * This is the consumer-side validator for InputCreditCard — the component only masks the
+ * input (clamping the month to 01-12 as you type); whether a *complete* date is acceptable
+ * is a business decision, so wire this to `state`/`errorMessage`:
+ *
+ * ```tsx
+ * <InputCreditCard
+ *   state={state}
+ *   errorMessage="Card has expired"
+ *   onExpiryDateChange={(v) => setState(isValidExpiryDate(v) ? "default" : "invalid")}
+ * />
+ * ```
+ *
+ * @param value The formatted expiry value (e.g. "04/27"); non-digits are ignored
+ * @param options.now Reference "now" (defaults to the current date) — pass for SSR/testing
+ * @returns Whether the expiry is a complete, non-expired MM/YY
+ */
+export declare const isValidExpiryDate: (value: string, options?: {
+    now?: Date;
+}) => boolean;
 /**
  * Apply phone number formatting (US format: (XXX) XXX-XXXX)
  * @param value The raw input value