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

package/dist/components/forms/SelectableCard/SelectableCard.js

@@ -1,53 +1,69 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useId } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
-import { CheckIcon } from '@heroicons/react/24/outline';
 import { cn } from '../../../utils/cn.js';
-import { useSelectableCardContext } from './SelectableCardContext.js';
+import { Radio } from '../Radio/Radio.js';
+import { Checkbox } from '../Checkbox/Checkbox.js';
+import { useOptionalSelectableCardContext } from './SelectableCardContext.js';
+import { selectableCardTheme } from './SelectableCard.theme.js';
 import { SelectableCardGroup } from './SelectableCardGroup.js';
 import { cardVariants } from './SelectableCard.animations.js';
 
-// ─── Radio Indicator ─────────────────────────────────────────────────────────
-const RadioIndicator = ({ checked }) => (jsxs("div", { className: "relative flex-shrink-0 flex items-center justify-center size-5", children: [jsx("div", { className: cn("size-5 rounded-full border-2 transition-colors duration-200", checked
-                ? "border-[var(--color-primary)]"
-                : "border-[var(--color-border)]") }), jsx("div", { className: cn("absolute inset-0 m-auto rounded-full bg-[var(--color-primary)] transition-all duration-200", checked ? "size-2.5 opacity-100" : "size-0 opacity-0") })] }));
-// ─── Checkbox Indicator ──────────────────────────────────────────────────────
-const CheckboxIndicator = ({ checked }) => (jsx("div", { className: cn("flex-shrink-0 flex items-center justify-center size-5 rounded-[4px] border-2 transition-colors duration-200", checked
-        ? "border-[var(--color-primary)] bg-[var(--color-primary)]"
-        : "border-[var(--color-border)] bg-[var(--color-background)]"), children: checked && jsx(CheckIcon, { className: "size-3.5 stroke-white", strokeWidth: 3 }) }));
 // ─── SelectableCard ──────────────────────────────────────────────────────────
-const SelectableCardRoot = React__default.forwardRef(({ value, disabled: cardDisabled, className, children, ...props }, ref) => {
-    const content = children;
-    const ctx = useSelectableCardContext();
+const SelectableCardRoot = React__default.forwardRef(({ value, disabled: cardDisabled, checked: standaloneChecked, onChange: standaloneOnChange, indicator: standaloneIndicator, indicatorPosition: cardIndicatorPosition, size: cardSize, className, children, onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...props }, ref) => {
+    var _a;
+    const ctx = useOptionalSelectableCardContext();
+    const isStandalone = ctx === undefined;
     const inputId = useId();
     const shouldReduceMotion = useReducedMotion();
-    const isDisabled = cardDisabled || ctx.disabled;
-    const isSelected = ctx.type === "single"
-        ? ctx.value === value
-        : Array.isArray(ctx.value) && ctx.value.includes(value);
+    const theme = isStandalone ? selectableCardTheme : ctx.theme;
+    const isDisabled = cardDisabled || (!isStandalone && ctx.disabled);
+    const isSelected = isStandalone
+        ? (standaloneChecked !== null && standaloneChecked !== void 0 ? standaloneChecked : false)
+        : ctx.type === "single"
+            ? ctx.value === value
+            : Array.isArray(ctx.value) && ctx.value.includes(value);
+    const resolvedIndicator = isStandalone
+        ? (standaloneIndicator !== null && standaloneIndicator !== void 0 ? standaloneIndicator : "radio")
+        : ctx.indicator;
+    const resolvedIndicatorPosition = cardIndicatorPosition !== null && cardIndicatorPosition !== void 0 ? cardIndicatorPosition : (isStandalone ? "end" : ctx.indicatorPosition);
+    const resolvedSize = cardSize !== null && cardSize !== void 0 ? cardSize : (isStandalone ? "md" : ctx.size);
+    const indicatorSize = "sm";
     const handleClick = () => {
         if (isDisabled)
             return;
-        ctx.onChange(value);
+        if (isStandalone) {
+            standaloneOnChange === null || standaloneOnChange === void 0 ? void 0 : standaloneOnChange(!isSelected, value);
+        }
+        else {
+            ctx.onChange(value);
+        }
     };
     const handleKeyDown = (e) => {
         if (isDisabled)
             return;
         if (e.key === " " || e.key === "Enter") {
             e.preventDefault();
-            ctx.onChange(value);
+            handleClick();
         }
     };
-    const inputType = ctx.type === "single" ? "radio" : "checkbox";
+    const inputType = isStandalone
+        ? "checkbox"
+        : ctx.type === "single"
+            ? "radio"
+            : "checkbox";
+    const role = isStandalone
+        ? "checkbox"
+        : ctx.type === "single"
+            ? "radio"
+            : "checkbox";
     const animated = !shouldReduceMotion && !isDisabled;
     const motionProps = animated
-        ? {
-            variants: cardVariants,
-            initial: "idle",
-            whileTap: "tap",
-        }
+        ? { variants: cardVariants, animate: "rest", whileTap: "press" }
         : {};
-    return (jsxs(motion.div, { ref: ref, role: ctx.type === "single" ? "radio" : "checkbox", "aria-checked": isSelected, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : 0, "data-selected": isSelected, "data-disabled": isDisabled || undefined, className: cn(ctx.theme.card, isSelected && ctx.theme.selectedCard, isDisabled && ctx.theme.disabledCard, className), onClick: handleClick, onKeyDown: handleKeyDown, ...motionProps, ...props, children: [jsx("input", { type: inputType, id: inputId, name: ctx.name, value: value, checked: isSelected, disabled: isDisabled, onChange: () => { }, className: "sr-only", tabIndex: -1, "aria-hidden": true }), jsx("div", { className: ctx.theme.contentWrapper, children: content }), ctx.indicator !== "none" && (jsx("div", { className: ctx.theme.indicator, children: ctx.indicator === "radio" ? (jsx(RadioIndicator, { checked: isSelected })) : (jsx(CheckboxIndicator, { checked: isSelected })) }))] }));
+    const indicatorNode = resolvedIndicator !== "none" && (jsx("div", { className: cn(theme.indicator, "pointer-events-none"), "aria-hidden": "true", children: resolvedIndicator === "radio" ? (jsx(Radio, { value: value, checked: isSelected, onChange: () => { }, state: isDisabled ? "disabled" : "default", size: indicatorSize })) : (jsx(Checkbox, { value: value, checked: isSelected, onChange: () => { }, state: isDisabled ? "disabled" : "default", size: indicatorSize })) }));
+    return (jsxs(motion.div, { ref: ref, role: role, "aria-checked": isSelected, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : 0, "data-selected": isSelected, "data-disabled": isDisabled || undefined, className: cn(theme.card, (_a = theme.cardSizes) === null || _a === void 0 ? void 0 : _a[resolvedSize], isSelected && theme.selectedCard, isDisabled && theme.disabledCard, className), onClick: handleClick, onKeyDown: handleKeyDown, ...motionProps, ...props, children: [jsx("input", { type: inputType, id: inputId, name: isStandalone ? undefined : ctx === null || ctx === void 0 ? void 0 : ctx.name, value: value, checked: isSelected, disabled: isDisabled, onChange: () => { }, className: "sr-only", tabIndex: -1, "aria-hidden": true }), resolvedIndicatorPosition === "start" && indicatorNode, jsx("div", { className: theme.contentWrapper, children: children }), resolvedIndicatorPosition === "end" && indicatorNode] }));
 });
 SelectableCardRoot.displayName = "SelectableCard";
 // ─── Compound Export ─────────────────────────────────────────────────────────

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

@@ -1,38 +1,28 @@
 const selectableCardTheme = {
     group: "flex flex-col gap-3",
     card: 
-    // Base layout
-    "relative flex items-center justify-between gap-4 rounded-[var(--radius-base)] p-4 cursor-pointer transition-[border-color,background-color,box-shadow,outline] duration-200 " +
-        // Default state - light
+    // Base layout — no justify-between; indicator position handled by render order
+    "relative flex items-start gap-3 rounded-[var(--radius-base)] cursor-pointer transition-[border-color,background-color,box-shadow,outline] duration-200 " +
+        // Default state
         "border border-[var(--color-border)] bg-[var(--color-surface)] " +
-        // Default state - dark
         "dark:bg-[var(--color-background)] " +
-        // Hover state - light
+        // Hover
         "hover:border-[var(--color-border-secondary)] " +
-        // Hover state - dark
-        "  " +
-        // Focus visible - light
+        // Focus visible
         "focus-visible:outline focus-visible:outline-offset-1 focus-visible:outline-[var(--color-primary)] " +
-        // Focus visible - dark
         "dark:focus-visible:outline-[var(--color-primary)]/50",
-    selectedCard: 
-    // Selected border & ring - light
-    "border-[var(--color-primary)] ring-2 ring-[var(--color-primary)]/10  " +
-        // Selected border & ring - dark
-        "dark:border-[var(--color-primary)] dark:ring-[var(--color-primary)]/20  " +
-        // Selected background gradient - light
-        "bg-[var(--color-primary-50)] " +
-        // Selected background gradient - dark
-        "dark:bg-[var(--color-background-secondary)] " +
-        // Selected hover - light
+    selectedCard: "border-[var(--color-primary)] ring-2 ring-[var(--color-primary)]/10 " +
+        "dark:border-[var(--color-primary)] dark:ring-[var(--color-primary)]/20 " +
         "hover:border-[var(--color-primary)] " +
-        // Selected hover - dark
-        "dark:hover:border-[var(--color-primary)] ",
-    disabledCard: 
-    // Disabled state
-    "opacity-50 cursor-not-allowed pointer-events-none",
+        "dark:hover:border-[var(--color-primary)]",
+    disabledCard: "opacity-50 cursor-not-allowed pointer-events-none",
     contentWrapper: "flex-1 min-w-0",
-    indicator: "flex-shrink-0",
+    indicator: "flex-shrink-0 -mt-0.5",
+    cardSizes: {
+        sm: "p-3",
+        md: "p-4",
+        lg: "p-5",
+    },
 };
 
 export { selectableCardTheme };

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

@@ -1,7 +1,8 @@
 import React from "react";
-import type { HTMLMotionProps } from "motion/react";
 export type SelectableCardType = "single" | "multiple";
 export type SelectableCardIndicator = "radio" | "checkbox" | "none";
+export type SelectableCardIndicatorPosition = "start" | "end";
+export type SelectableCardSize = "sm" | "md" | "lg";
 export interface SelectableCardTheme {
     group?: string;
     card?: string;
@@ -9,10 +10,13 @@ export interface SelectableCardTheme {
     disabledCard?: string;
     contentWrapper?: string;
     indicator?: string;
+    cardSizes?: Record<SelectableCardSize, string>;
 }
 export interface SelectableCardContextValue {
     type: SelectableCardType;
     indicator: SelectableCardIndicator;
+    indicatorPosition: SelectableCardIndicatorPosition;
+    size: SelectableCardSize;
     value: string | string[];
     onChange: (cardValue: string) => void;
     disabled: boolean;
@@ -21,14 +25,22 @@ export interface SelectableCardContextValue {
 }
 export interface SelectableCardGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
     type?: SelectableCardType;
-    value: string | string[];
-    onChange: (value: string | string[]) => void;
+    value?: string | string[];
+    defaultValue?: string | string[];
+    onChange?: (value: string | string[]) => void;
     indicator?: SelectableCardIndicator;
+    indicatorPosition?: SelectableCardIndicatorPosition;
+    size?: SelectableCardSize;
     disabled?: boolean;
     name?: string;
     theme?: Partial<SelectableCardTheme>;
 }
-export interface SelectableCardProps extends Omit<HTMLMotionProps<"div">, "value"> {
+export interface SelectableCardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "value" | "onChange"> {
     value: string;
     disabled?: boolean;
+    checked?: boolean;
+    onChange?: (checked: boolean, value: string) => void;
+    indicator?: SelectableCardIndicator;
+    indicatorPosition?: SelectableCardIndicatorPosition;
+    size?: SelectableCardSize;
 }

package/dist/components/forms/SelectableCard/SelectableCardContext.d.ts

@@ -1,3 +1,4 @@
 import type { SelectableCardContextValue } from "./SelectableCard.types";
 export declare const SelectableCardContext: import("react").Context<SelectableCardContextValue | undefined>;
 export declare function useSelectableCardContext(): SelectableCardContextValue;
+export declare function useOptionalSelectableCardContext(): SelectableCardContextValue | undefined;

package/dist/components/forms/SelectableCard/SelectableCardContext.js

@@ -1,12 +1,10 @@
+"use client";
 import { createContext, useContext } from 'react';
 
 const SelectableCardContext = createContext(undefined);
-function useSelectableCardContext() {
-    const context = useContext(SelectableCardContext);
-    if (!context) {
-        throw new Error("SelectableCard must be used within a SelectableCard.Group");
-    }
-    return context;
+// Used by SelectableCard itself — returns undefined when used standalone
+function useOptionalSelectableCardContext() {
+    return useContext(SelectableCardContext);
 }
 
-export { SelectableCardContext, useSelectableCardContext };
+export { SelectableCardContext, useOptionalSelectableCardContext };

package/dist/components/forms/SelectableCard/SelectableCardGroup.js

@@ -1,35 +1,57 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import React__default, { useId, useMemo } from 'react';
+import React__default, { useId, useState, useMemo, useCallback } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { selectableCardTheme } from './SelectableCard.theme.js';
 import { SelectableCardContext } from './SelectableCardContext.js';
 
-const SelectableCardGroup = React__default.forwardRef(({ type = "single", value, onChange, indicator, disabled = false, name, className, theme: customTheme, children, ...props }, ref) => {
+const SelectableCardGroup = React__default.forwardRef(({ type = "single", value, defaultValue, onChange, indicator, indicatorPosition = "end", size = "md", disabled = false, name, className, theme: customTheme, children, ...props }, ref) => {
     const autoId = useId();
     const groupName = name !== null && name !== void 0 ? name : `selectable-card-${autoId}`;
+    const isControlled = value !== undefined;
+    const [internalValue, setInternalValue] = useState(() => {
+        if (defaultValue !== undefined) {
+            if (process.env.NODE_ENV !== "production") {
+                if (type === "single" && Array.isArray(defaultValue)) {
+                    console.warn("[SelectableCard.Group]: defaultValue is an array but type is 'single'. Use a string.");
+                }
+                if (type === "multiple" && typeof defaultValue === "string") {
+                    console.warn("[SelectableCard.Group]: defaultValue is a string but type is 'multiple'. Use an array.");
+                }
+            }
+            return defaultValue;
+        }
+        return type === "single" ? "" : [];
+    });
+    const resolvedValue = value !== undefined ? value : internalValue;
     const resolvedIndicator = indicator !== null && indicator !== void 0 ? indicator : (type === "single" ? "radio" : "checkbox");
     const theme = useMemo(() => ({ ...selectableCardTheme, ...customTheme }), [customTheme]);
-    const handleChange = (cardValue) => {
+    const handleChange = useCallback((cardValue) => {
+        let next;
         if (type === "single") {
-            onChange(cardValue);
+            next = cardValue;
         }
         else {
-            const current = Array.isArray(value) ? value : [];
-            const next = current.includes(cardValue)
+            const current = Array.isArray(resolvedValue) ? resolvedValue : [];
+            next = current.includes(cardValue)
                 ? current.filter((v) => v !== cardValue)
                 : [...current, cardValue];
-            onChange(next);
         }
-    };
+        if (!isControlled)
+            setInternalValue(next);
+        onChange === null || onChange === void 0 ? void 0 : onChange(next);
+    }, [type, resolvedValue, isControlled, onChange]);
     const contextValue = useMemo(() => ({
         type,
         indicator: resolvedIndicator,
-        value,
+        indicatorPosition,
+        size,
+        value: resolvedValue,
         onChange: handleChange,
         disabled,
         name: groupName,
         theme,
-    }), [type, resolvedIndicator, value, disabled, groupName, theme]);
+    }), [type, resolvedIndicator, indicatorPosition, size, resolvedValue, handleChange, disabled, groupName, theme]);
     return (jsx(SelectableCardContext.Provider, { value: contextValue, children: jsx("div", { ref: ref, role: type === "single" ? "radiogroup" : "group", className: cn(theme.group, className), ...props, children: children }) }));
 });
 SelectableCardGroup.displayName = "SelectableCard.Group";

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

@@ -1,3 +1,3 @@
 export { SelectableCard } from "./SelectableCard";
-export type { SelectableCardProps, SelectableCardGroupProps, SelectableCardType, SelectableCardIndicator, SelectableCardTheme, } from "./SelectableCard.types";
+export type { SelectableCardProps, SelectableCardGroupProps, SelectableCardType, SelectableCardIndicator, SelectableCardIndicatorPosition, SelectableCardSize, SelectableCardTheme, } from "./SelectableCard.types";
 export { selectableCardTheme } from "./SelectableCard.theme";

package/dist/components/forms/Signature/Signature.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useRef, useState, useEffect, useCallback } from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -5,7 +6,7 @@ import { signatureTheme } from './Signature.theme.js';
 import { FormLabel } from '../FormLabel/FormLabel.js';
 import { Button } from '../../core/Button/Button.js';
 
-const Signature = React__default.forwardRef(({ id, label, labelClassName, helperText, helperTextClassName, wrapperClassName, size = 'md', state = 'default', required = false, disabled = false, width = 400, height = 200, strokeColor = '#000000', strokeWidth = 2, backgroundColor = 'transparent', className, theme: customTheme = {}, onChange, onClear, showControls = true, placeholder = 'Sign here', ...props }, ref) => {
+const Signature = React__default.forwardRef(({ id, label, labelClassName, helperText, errorMessage, helperTextClassName, wrapperClassName, size = 'md', state = 'default', required = false, disabled = false, width = 400, height = 200, strokeColor = '#000000', strokeWidth = 2, backgroundColor = 'transparent', className, theme: customTheme = {}, onChange, onClear, showControls = true, placeholder = 'Sign here', ...props }, ref) => {
     var _a, _b;
     const canvasRef = useRef(null);
     const [isDrawing, setIsDrawing] = useState(false);
@@ -101,6 +102,11 @@ const Signature = React__default.forwardRef(({ id, label, labelClassName, helper
         lastPointRef.current = currentPoint;
     }, [isDisabled, isDrawing, getPointFromEvent]);
     const stopDrawing = useCallback(() => {
+        // A mouseup/touchend/mouseleave can fire on a disabled pad (e.g. it was
+        // disabled mid-drag, or the browser still delivers the trailing event) —
+        // bail before touching state or emitting onChange.
+        if (isDisabled)
+            return;
         setIsDrawing(false);
         lastPointRef.current = null;
         // Only call toDataURL and onChange on mouseup/touchend, not on every draw event
@@ -109,7 +115,7 @@ const Signature = React__default.forwardRef(({ id, label, labelClassName, helper
             const dataURL = canvas.toDataURL();
             onChange(dataURL);
         }
-    }, [onChange]);
+    }, [isDisabled, onChange]);
     const clear = useCallback(() => {
         const canvas = canvasRef.current;
         if (!canvas)
@@ -145,7 +151,11 @@ const Signature = React__default.forwardRef(({ id, label, labelClassName, helper
     const sizeClasses = ((_a = theme.sizes) === null || _a === void 0 ? void 0 : _a[size]) || '';
     const stateClasses = ((_b = theme.states) === null || _b === void 0 ? void 0 : _b[state]) || '';
     const helperTextClasses = theme.helperText || '';
-    return (jsxs("div", { className: cn(wrapperClasses, stateClass, wrapperClassName), children: [label && (jsx("div", { className: "mb-1", children: jsx(FormLabel, { htmlFor: signatureId, className: labelClassName, state: state, required: required, children: label }) })), jsx("div", { className: cn(inputGroupClasses, sizeClasses, stateClasses, className), style: { width, height }, children: jsxs("div", { ref: ref, className: baseClasses, ...props, children: [jsx("canvas", { ref: canvasRef, id: signatureId, className: cn(theme.canvasStyle, customTheme.canvasStyle), tabIndex: isDisabled ? -1 : 0, onMouseDown: startDrawing, onMouseMove: draw, onMouseUp: stopDrawing, onMouseLeave: stopDrawing, onTouchStart: startDrawing, onTouchMove: draw, onTouchEnd: stopDrawing, "aria-label": label || 'Signature canvas', "aria-required": required, "aria-invalid": isInvalid, "aria-disabled": isDisabled }), isEmpty && placeholder && !isDisabled && (jsx("div", { className: cn(theme.placeholderStyle, customTheme.placeholderStyle), children: placeholder })), showControls && !isDisabled && (jsxs("div", { className: cn(theme.controlsStyle, customTheme.controlsStyle), children: [jsx(Button, { size: "sm", variant: "outline", color: 'neutral', onClick: clear, type: "button", children: "Clear" }), jsx(Button, { size: "sm", variant: "filled", onClick: save, disabled: isEmpty, type: "button", children: "Save" })] }))] }) }), helperText && (jsx("div", { className: cn(helperTextClasses, helperTextClassName), children: helperText }))] }));
+    // errorMessage takes precedence over helperText while invalid; helperText
+    // behavior is unchanged otherwise.
+    const displayedMessage = isInvalid && errorMessage ? errorMessage : helperText;
+    const messageId = `${signatureId}-message`;
+    return (jsxs("div", { className: cn(wrapperClasses, stateClass, wrapperClassName), children: [label && (typeof label === 'string' ? (jsx("div", { className: "mb-1", children: jsx(FormLabel, { htmlFor: signatureId, className: labelClassName, state: state, required: required, children: label }) })) : (label)), jsx("div", { className: cn(inputGroupClasses, sizeClasses, stateClasses, className), style: { width, height }, children: jsxs("div", { ref: ref, className: baseClasses, ...props, children: [jsx("canvas", { ref: canvasRef, id: signatureId, className: cn(theme.canvasStyle, customTheme.canvasStyle), tabIndex: isDisabled ? -1 : 0, onMouseDown: startDrawing, onMouseMove: draw, onMouseUp: stopDrawing, onMouseLeave: stopDrawing, onTouchStart: startDrawing, onTouchMove: draw, onTouchEnd: stopDrawing, "aria-label": typeof label === 'string' ? label : 'Signature canvas', "aria-required": required, "aria-invalid": isInvalid, "aria-disabled": isDisabled, "aria-describedby": displayedMessage ? messageId : undefined }), isEmpty && placeholder && !isDisabled && (jsx("div", { className: cn(theme.placeholderStyle, customTheme.placeholderStyle), children: placeholder })), showControls && !isDisabled && (jsxs("div", { className: cn(theme.controlsStyle, customTheme.controlsStyle), children: [jsx(Button, { size: "sm", variant: "outline", color: 'mono', onClick: clear, type: "button", children: "Clear" }), jsx(Button, { size: "sm", variant: "filled", onClick: save, disabled: isEmpty, type: "button", children: "Save" })] }))] }) }), displayedMessage && (typeof displayedMessage === 'string' ? (jsx("div", { id: messageId, role: isInvalid ? 'alert' : undefined, className: cn(helperTextClasses, helperTextClassName), children: displayedMessage })) : (displayedMessage))] }));
 });
 Signature.displayName = 'Signature';
 

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

@@ -1,4 +1,4 @@
-import { HTMLAttributes } from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
 /**
  * Signature component size variants
  */
@@ -51,11 +51,17 @@ export interface SignatureProps extends Omit<HTMLAttributes<HTMLDivElement>, 'on
     /** Unique identifier for the signature field */
     id?: string;
     /** Label text for the signature */
-    label?: string;
+    label?: ReactNode;
     /** Additional class name for the label */
     labelClassName?: string;
     /** Helper text displayed below the signature */
-    helperText?: string;
+    helperText?: 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?: ReactNode;
     /** Additional class name for the helper text */
     helperTextClassName?: string;
     /** Additional class name for the wrapper */

package/dist/components/forms/Slider/Slider.js

@@ -1,15 +1,36 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default, { useRef, useState, useCallback, useMemo } from 'react';
+import React__default, { useRef, useEffect, useState, useCallback, useMemo } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
+import { createPressVariants } from '../../core/shared/interaction.animations.js';
 import { FormLabel } from '../FormLabel/FormLabel.js';
+import { Tooltip } from '../../core/Tooltip/Tooltip.js';
+import '../../core/Tooltip/Tooltip.animations.js';
 import { sliderTheme } from './Slider.theme.js';
 import { cn } from '../../../utils/cn.js';
 
+// Shared press physics (fast tween in, stiff spring out) with a hover lift,
+// wired as `animate="rest"` + `whileTap="press"` + `whileHover="hover"`.
+const thumbPressVariants = createPressVariants(0.95, 1.12);
 const Slider = React__default.forwardRef(({ state = "default", className = "", label, labelClassName = "", helperText, helperTextClassName = "", wrapperClassName = "", min = 0, max = 100, step = 1, value, defaultValue, onChange, onChangeCommitted, showValue = false, unit = "", showMinMax = false, showTicks = false, tickStep, range = false, iconStart, iconEnd, theme = {}, required = false, name, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby, ...props }, ref) => {
     var _a;
     const trackRef = useRef(null);
+    // Track active pointer listeners so they can be cleaned up on unmount during a drag
+    const activeListenersRef = useRef({ move: null, up: null });
+    // Cleanup on unmount — removes any lingering listeners if component unmounts mid-drag
+    useEffect(() => {
+        return () => {
+            const { move, up } = activeListenersRef.current;
+            if (move)
+                document.removeEventListener("pointermove", move);
+            if (up)
+                document.removeEventListener("pointerup", up);
+        };
+    }, []);
     const generatedId = React__default.useId();
     const sliderId = id || generatedId;
-    const helperTextId = helperText ? `${sliderId}-helper` : undefined;
+    const shouldReduceMotion = useReducedMotion();
+    const helperTextId = typeof helperText === 'string' && helperText ? `${sliderId}-helper` : undefined;
     // Handle controlled/uncontrolled value
     const [internalValue, setInternalValue] = useState((_a = value !== null && value !== void 0 ? value : defaultValue) !== null && _a !== void 0 ? _a : (range ? [min, min] : min));
     const currentValue = value !== null && value !== void 0 ? value : internalValue;
@@ -68,11 +89,13 @@ const Slider = React__default.forwardRef(({ state = "default", className = "", l
             }
         };
         const handleEnd = () => {
+            activeListenersRef.current = { move: null, up: null };
             setDragIndex(null);
             onChangeCommitted === null || onChangeCommitted === void 0 ? void 0 : onChangeCommitted(currentValue);
             document.removeEventListener("pointermove", handleMove);
             document.removeEventListener("pointerup", handleEnd);
         };
+        activeListenersRef.current = { move: handleMove, up: handleEnd };
         document.addEventListener("pointermove", handleMove);
         document.addEventListener("pointerup", handleEnd);
     }, [
@@ -216,21 +239,33 @@ const Slider = React__default.forwardRef(({ state = "default", className = "", l
         }
         return `${currentValue}${unit}`;
     };
-    return (jsxs("div", { className: cn(mergedTheme.wrapperStyle, wrapperClassName), ref: ref, ...props, children: [label && (jsx(FormLabel, { htmlFor: sliderId, required: required, className: cn(mergedTheme.labelStyle, labelClassName), children: label })), jsxs("div", { className: "flex items-center gap-4", children: [iconStart && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-muted)]", children: iconStart })), showMinMax && (jsx("span", { className: cn(mergedTheme.minMaxLabelStyle), children: min })), jsxs("div", { className: cn(mergedTheme.rootStyle, className), "data-disabled": isDisabled || undefined, "data-invalid": isInvalid || undefined, "data-orientation": "horizontal", children: [jsxs("div", { ref: trackRef, className: mergedTheme.trackStyle, onPointerDown: handleTrackClick, role: "presentation", children: [jsx("div", { className: mergedTheme.rangeStyle, style: getFilledTrackStyle() }), showTicks &&
+    return (jsxs("div", { className: cn(mergedTheme.wrapperStyle, wrapperClassName), ref: ref, ...props, children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: sliderId, state: state, required: required, className: cn(mergedTheme.labelStyle, labelClassName), children: label })) : (label)), jsxs("div", { className: "flex items-center gap-4", children: [iconStart && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-muted)]", children: iconStart })), showMinMax && (jsx("span", { className: cn(mergedTheme.minMaxLabelStyle), children: min })), jsxs("div", { className: cn(mergedTheme.rootStyle, className), "data-disabled": isDisabled || undefined, "data-invalid": isInvalid || undefined, "data-orientation": "horizontal", children: [jsxs("div", { ref: trackRef, className: mergedTheme.trackStyle, onPointerDown: handleTrackClick, role: "presentation", children: [jsx("div", { className: mergedTheme.rangeStyle, style: getFilledTrackStyle() }), showTicks &&
                                         ticks.map((tick) => {
                                             const percentage = getPercentage(tick);
                                             return (jsx("div", { className: mergedTheme.tickStyle, style: { left: `${percentage}%` } }, tick));
                                         })] }), values.map((val, index) => {
                                 const percentage = getPercentage(val);
-                                return (jsx("div", { className: cn(mergedTheme.thumbStyle, "outline-[1px] outline-white/50 ring-0 shadow-none p-0 overflow-visible"), style: {
+                                return (jsx(motion.div, { className: mergedTheme.thumbStyle, style: {
                                         left: `${percentage}%`,
-                                        transform: "translate(-50%, -50%)",
                                         position: "absolute",
                                         top: "50%",
-                                    }, onPointerDown: (e) => handlePointerDown(e, index), onKeyDown: (e) => handleKeyDown(e, index), role: "slider", "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": val, "aria-orientation": "horizontal", "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : (range ? `Slider thumb ${index + 1}` : "Slider"), "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby !== null && ariaDescribedby !== void 0 ? ariaDescribedby : helperTextId, tabIndex: isDisabled ? -1 : 0, "data-disabled": isDisabled || undefined, "data-invalid": isInvalid || undefined }, index));
+                                        x: "-50%",
+                                        y: "-50%",
+                                    }, onPointerDown: (e) => handlePointerDown(e, index), onKeyDown: (e) => handleKeyDown(e, index), role: "slider", "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": val, "aria-orientation": "horizontal", "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : (range ? `Slider thumb ${index + 1}` : "Slider"), "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby !== null && ariaDescribedby !== void 0 ? ariaDescribedby : helperTextId, "aria-invalid": isInvalid || undefined, tabIndex: isDisabled ? -1 : 0, "data-disabled": isDisabled || undefined, "data-invalid": isInvalid || undefined, ...(isDisabled || shouldReduceMotion
+                                        ? {}
+                                        : {
+                                            variants: thumbPressVariants,
+                                            animate: "rest",
+                                            whileHover: "hover",
+                                            whileTap: "press",
+                                        }), children: jsx(Tooltip, { content: jsxs("span", { className: "whitespace-nowrap", children: [val, unit] }), isOpen: dragIndex === index, placement: "top", disabled: isDisabled, triggerClassName: "block w-full h-full", 
+                                        // Thumb moves via left%/transform on every pointermove during
+                                        // a drag, with no scroll/resize event to key off — force the
+                                        // portal to recalc so it tracks the thumb.
+                                        recalcTrigger: val, children: jsx("div", { className: "w-full h-full", "aria-hidden": "true" }) }) }, index));
                             }), name && (jsx("input", { type: "hidden", name: name, value: Array.isArray(currentValue)
                                     ? currentValue.join(",")
-                                    : currentValue }))] }), showMinMax && (jsx("span", { className: cn(mergedTheme.minMaxLabelStyle), children: max })), showValue && (jsx("div", { className: cn(mergedTheme.valueDisplayStyle), children: formatValueDisplay() })), iconEnd && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-muted)]", children: iconEnd }))] }), helperText && (jsx("div", { id: helperTextId, className: cn(mergedTheme.helperTextStyle, helperTextClassName), children: helperText }))] }));
+                                    : currentValue }))] }), showMinMax && (jsx("span", { className: cn(mergedTheme.minMaxLabelStyle), children: max })), showValue && (jsx("div", { className: cn(mergedTheme.valueDisplayStyle), children: formatValueDisplay() })), iconEnd && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-muted)]", children: iconEnd }))] }), helperText && (typeof helperText === 'string' ? (jsx("div", { id: helperTextId, className: cn(mergedTheme.helperTextStyle, helperTextClassName), children: helperText })) : (helperText))] }));
 });
 Slider.displayName = "Slider";
 

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

@@ -10,17 +10,23 @@ const sliderTheme = {
     // Root container with layout
     rootStyle: "relative flex items-center w-full touch-none select-none data-[orientation=vertical]:flex-col data-[orientation=vertical]:h-full",
     // Track (background)
-    trackStyle: "relative w-full h-2 grow rounded-full bg-neutral-200 overflow-hidden data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 data-[orientation=vertical]:w-2 data-[orientation=vertical]:h-full",
+    trackStyle: "relative w-full h-2 grow rounded-full bg-[var(--color-surface-sunken)] overflow-hidden data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 data-[orientation=vertical]:w-2 data-[orientation=vertical]:h-full shadow-inner-real-sm",
     // Range (filled portion) - rounded to match track clipping
-    rangeStyle: "absolute h-full bg-gradient-to-r from-[var(--color-primary-500)] to-[var(--color-primary-700)] transition-all rounded-full data-[disabled]:bg-[var(--color-background-disabled)] data-[invalid]:bg-[var(--color-danger)]",
-    // Thumb (draggable handle)
-    thumbStyle: "block h-5 w-8 rounded-full border-2 border-[var(--color-primary)] ring-2 ring-white shadow-sm cursor-grab active:cursor-grabbing focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-border)] focus-visible:ring-offset-2 transition-all hover:scale-110 disabled:cursor-not-allowed disabled:bg-[var(--color-background-disabled)] disabled:hover:scale-100 data-[disabled]:cursor-not-allowed data-[disabled]:bg-[var(--color-background-disabled)] data-[disabled]:border-[var(--color-border)] data-[disabled]:hover:scale-100 data-[invalid]:border-[var(--color-danger)] data-[invalid]:focus-visible:ring-[var(--color-danger)] glass-effect-5",
+    rangeStyle: "absolute h-full bg-gradient-to-r from-[var(--color-primary-500)] to-[var(--color-primary-700)] rounded-full data-[disabled]:bg-[var(--color-background-disabled)] data-[invalid]:bg-[var(--color-danger)]",
+    // Thumb (draggable handle). Solid surface bg (backdrop-filter glitches in
+    // WebKit under 3D transforms); glass look = specular inset highlights +
+    // shadow-lg-strength drop shadow, with the white speculars dialed down in
+    // dark mode where they would read as a glowing rim.
+    thumbStyle: "block h-5 w-7 rounded-full p-0 bg-[var(--color-surface)] outline-[2px] outline-[var(--color-border)]/80 ring-0 " +
+        "shadow-[inset_1px_1px_0_rgba(255,255,255,0.45),inset_1px_3px_0_rgba(0,0,0,0.03),inset_0_0_14px_rgba(255,255,255,0.15),inset_-1px_-1px_0_rgba(0,0,0,0.06),0_10px_15px_-3px_rgba(0,0,0,0.1),0_4px_6px_-4px_rgba(0,0,0,0.1)] " +
+        "dark:shadow-[inset_1px_1px_0_rgba(255,255,255,0.12),inset_1px_3px_0_rgba(0,0,0,0.15),inset_0_0_14px_rgba(255,255,255,0.04),inset_-1px_-1px_0_rgba(0,0,0,0.35),0_10px_15px_-3px_rgba(0,0,0,0.45),0_4px_6px_-4px_rgba(0,0,0,0.45)] " +
+        "cursor-grab active:cursor-grabbing focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-border)] focus-visible:ring-offset-2 data-[disabled]:cursor-not-allowed data-[invalid]:focus-visible:ring-[var(--color-danger)]",
     // Value display
     valueDisplayStyle: "text-sm font-medium text-[var(--color-text-secondary)] w-fit min-w-12",
     // Min/max labels
     minMaxLabelStyle: "text-sm font-medium text-[var(--color-text-muted)]",
     // Tick marks
-    tickStyle: "absolute w-0.5 h-2 bg-white/60 -translate-x-0.5 pointer-events-none",
+    tickStyle: "absolute w-0.5 h-2 bg-[var(--color-border)] -translate-x-0.5 pointer-events-none",
 };
 
 export { sliderTheme };

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

@@ -26,9 +26,9 @@ export interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     /** The state of the slider (default, disabled, invalid) */
     state?: SliderState;
     /** Optional label text for the slider */
-    label?: string;
+    label?: React.ReactNode;
     /** Optional helper text displayed below the slider */
-    helperText?: string;
+    helperText?: React.ReactNode;
     /** Minimum value for the slider */
     min?: number;
     /** Maximum value for the slider */