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

package/dist/components/forms/Switch/Switch.js

@@ -1,21 +1,28 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useState } from 'react';
 import { FormLabel } from '../FormLabel/FormLabel.js';
-import { motion } from 'motion/react';
+import { useReducedMotion, motion } from 'motion/react';
 import { switchTheme, thumbPositions } from './Switch.theme.js';
 import { cn } from '../../../utils/cn.js';
 
+const indicatorTransition = {
+    duration: 0.6,
+    ease: [0.22, 1, 0.36, 1],
+};
 /**
  * Switch component for toggling between two states
  */
-const Switch = React__default.forwardRef(({ id, checked: controlledChecked, onChange, label, description, state = "default", labelPosition = "end", theme, className, ...rest }, ref) => {
-    const [internalChecked, setInternalChecked] = useState(false);
+const Switch = React__default.forwardRef(({ id, checked: controlledChecked, defaultChecked, onChange, label, description, state = "default", labelPosition = "end", size = "md", theme, className, name, value, required, form, ...rest }, ref) => {
+    const generatedId = React__default.useId();
+    const switchId = id !== null && id !== void 0 ? id : generatedId;
+    const shouldReduceMotion = useReducedMotion();
+    const [internalChecked, setInternalChecked] = useState(defaultChecked !== null && defaultChecked !== void 0 ? defaultChecked : false);
     // Determine if component is controlled or uncontrolled
     const isControlled = controlledChecked !== undefined;
     const isChecked = isControlled ? controlledChecked : internalChecked;
     // Derive state flags
     const isDisabled = state === "disabled";
-    const isInvalid = state === "invalid";
     const handleChange = (e) => {
         if (isDisabled)
             return;
@@ -24,27 +31,40 @@ const Switch = React__default.forwardRef(({ id, checked: controlledChecked, onCh
         }
         onChange === null || onChange === void 0 ? void 0 : onChange(e.target.checked);
     };
-    const handleTrackClick = () => {
-        if (!isDisabled) {
-            const newValue = !isChecked;
-            if (!isControlled) {
-                setInternalChecked(newValue);
-            }
-            onChange === null || onChange === void 0 ? void 0 : onChange(newValue);
-        }
-    };
     // Label and description content
-    const labelContent = label || description ? (jsxs("div", { className: "flex grow flex-col", children: [label && (jsx(FormLabel, { htmlFor: id, state: state, children: label })), description && (jsx("div", { className: cn(switchTheme.description, theme === null || theme === void 0 ? void 0 : theme.description), children: description }))] })) : null;
-    // Build data attributes for state-based styling
+    const labelContent = label || description ? (jsxs("div", { className: "flex grow flex-col", children: [label &&
+                (typeof label === "string" ? (jsx(FormLabel, { htmlFor: switchId, state: state, children: label })) : (label)), description &&
+                (typeof description === "string" ? (jsx("div", { className: cn(switchTheme.description, theme === null || theme === void 0 ? void 0 : theme.description), children: description })) : (description))] })) : null;
+    // Hook only — emitted as `data-state` for consumer CSS / tests, NOT used for styling
     const trackDataState = isDisabled
         ? "disabled"
-        : isInvalid
-            ? "invalid"
-            : isChecked
-                ? "checked"
-                : "unchecked";
+        : isChecked
+            ? "checked"
+            : "unchecked";
+    // Resolve track state styling in JS (base theme + per-state theme override),
+    // layered so `className`/`theme` overrides win — see Switch.theme.ts rationale.
+    const resolveTrackState = (key) => { var _a; return cn(switchTheme.trackStates[key], (_a = theme === null || theme === void 0 ? void 0 : theme.trackStates) === null || _a === void 0 ? void 0 : _a[key]); };
+    const trackStateClasses = cn(isChecked ? resolveTrackState("checked") : resolveTrackState("unchecked"), isDisabled && resolveTrackState("disabled"));
     // Switch toggle component
-    const switchToggle = (jsxs("div", { className: "relative flex items-center h-6", children: [jsx("input", { ref: ref, type: "checkbox", id: id, checked: isChecked, onChange: handleChange, disabled: isDisabled, className: "sr-only", "aria-checked": isChecked, "aria-invalid": isInvalid }), jsx("div", { className: cn(switchTheme.track, theme === null || theme === void 0 ? void 0 : theme.track), "data-state": trackDataState, onClick: handleTrackClick, children: jsx(motion.div, { className: cn(switchTheme.thumb, theme === null || theme === void 0 ? void 0 : theme.thumb), initial: false, animate: isChecked ? thumbPositions.checked : thumbPositions.unchecked, transition: { type: "spring", stiffness: 500, damping: 30 } }) })] }));
+    const switchToggle = (jsx("div", { className: "relative flex items-center h-6", children: jsxs("label", { htmlFor: switchId, className: "contents", children: [jsx("input", { ref: ref, type: "checkbox", id: switchId, checked: isChecked, onChange: handleChange, disabled: isDisabled, className: "peer sr-only", name: name, value: value, required: required, form: form }), jsxs("div", { className: cn(switchTheme.track, switchTheme.trackSizes[size], trackStateClasses, theme === null || theme === void 0 ? void 0 : theme.track), "data-state": trackDataState, "aria-hidden": "true", children: [jsx(motion.div, { className: cn(switchTheme.thumb, switchTheme.thumbSizes[size], 
+                            // On the checked/primary track the white knob would vanish on a
+                            // light primary (e.g. a near-white primary in dark mode), so the
+                            // ON thumb adopts the track's contrast color: white on a dark
+                            // primary (unchanged), dark on a light primary. The OFF thumb keeps
+                            // the white gradient — it sits on the neutral off-track, never white.
+                            isChecked && "bg-none bg-[var(--color-primary-contrast)]", !isDisabled && "group-hover:shadow-xl", theme === null || theme === void 0 ? void 0 : theme.thumb), initial: false, animate: isChecked
+                                ? thumbPositions[size].checked
+                                : thumbPositions[size].unchecked, transition: shouldReduceMotion
+                                ? { duration: 0 }
+                                : { type: "spring", stiffness: 500, damping: 30 }, whileTap: isDisabled || shouldReduceMotion ? undefined : { scale: 0.94 } }), jsx(motion.div, { className: "pointer-events-none absolute inset-y-0 left-1.5 inline-flex w-2.5 items-center justify-center", initial: false, animate: shouldReduceMotion
+                                ? { opacity: isChecked ? 1 : 0, x: 0, scale: 1 }
+                                : isChecked
+                                    ? { opacity: 1, x: 0, scale: 1 }
+                                    : { opacity: 0, x: -4, scale: 0.78 }, transition: shouldReduceMotion ? { duration: 0 } : indicatorTransition, children: jsx("div", { className: "size-2 rounded-full border-[1.5px] border-[var(--color-primary-contrast)]/50" }) }), jsx(motion.div, { className: "pointer-events-none absolute inset-y-0 right-1.5 inline-flex w-2.5 items-center justify-center", initial: false, animate: shouldReduceMotion
+                                ? { opacity: isChecked ? 0 : 1, x: 0, scaleY: 1 }
+                                : isChecked
+                                    ? { opacity: 0, x: 4, scaleY: 0.6 }
+                                    : { opacity: 1, x: 0, scaleY: 1 }, transition: shouldReduceMotion ? { duration: 0 } : indicatorTransition, children: jsx("div", { className: "w-[1.5px] h-2 rounded-full bg-white/50" }) })] })] }) }));
     return (jsxs("div", { className: cn(switchTheme.container, labelPosition === "start" ? "flex-row-reverse" : "flex-row", theme === null || theme === void 0 ? void 0 : theme.container, className), ...rest, children: [labelContent, switchToggle] }));
 });
 Switch.displayName = "Switch";

package/dist/components/forms/Switch/Switch.theme.d.ts

@@ -1,18 +1,48 @@
 import { SwitchTheme } from "./Switch.types";
 /**
  * Default theme configuration for the Switch component
+ *
+ * Gold-standard state styling: track state classes live in `trackStates` as
+ * plain utility strings and are resolved in JS at render time (see Switch.tsx),
+ * NOT as `data-[state=*]:` Tailwind variants. A data-variant compiles to a
+ * class + attribute selector (specificity 0,2,0) that beats a plain `className`
+ * override (0,1,0) regardless of order, silently breaking the shadcn rule
+ * "className override = highest priority". We still emit `data-state` on the
+ * track as a hook for consumer CSS / tests — we just don't *style* with it.
  */
 export declare const switchTheme: SwitchTheme;
 /**
  * Thumb position values for animation
  */
 export declare const thumbPositions: {
-    checked: {
-        x: number;
-        y: number;
+    sm: {
+        checked: {
+            x: number;
+            y: number;
+        };
+        unchecked: {
+            x: number;
+            y: number;
+        };
     };
-    unchecked: {
-        x: number;
-        y: number;
+    md: {
+        checked: {
+            x: number;
+            y: number;
+        };
+        unchecked: {
+            x: number;
+            y: number;
+        };
+    };
+    lg: {
+        checked: {
+            x: number;
+            y: number;
+        };
+        unchecked: {
+            x: number;
+            y: number;
+        };
     };
 };

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

@@ -1,18 +1,59 @@
 /**
  * Default theme configuration for the Switch component
+ *
+ * Gold-standard state styling: track state classes live in `trackStates` as
+ * plain utility strings and are resolved in JS at render time (see Switch.tsx),
+ * NOT as `data-[state=*]:` Tailwind variants. A data-variant compiles to a
+ * class + attribute selector (specificity 0,2,0) that beats a plain `className`
+ * override (0,1,0) regardless of order, silently breaking the shadcn rule
+ * "className override = highest priority". We still emit `data-state` on the
+ * track as a hook for consumer CSS / tests — we just don't *style* with it.
  */
 const switchTheme = {
     container: "flex w-full justify-between items-center gap-4",
-    track: "w-12 h-6 rounded-full transition-colors cursor-pointer shadow-inner bg-[var(--color-border)] data-[state=checked]:bg-[var(--color-primary)] data-[state=disabled]:bg-[var(--color-background-disabled)] data-[state=disabled]:cursor-not-allowed data-[state=invalid]:border-2 data-[state=invalid]:border-[var(--color-danger)]",
-    thumb: "w-7 h-5 rounded-full shadow-md glass-effect !bg-white/80",
+    // Structural base only — no state colors (those live in `trackStates`)
+    track: "group rounded-full cursor-pointer shadow-inner-real-sm transition-colors duration-500 motion-reduce:transition-none outline-1 outline-[var(--color-border)] peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-[var(--color-primary-600)]",
+    // Resolved in JS and layered via cn() so later keys win (tailwind-merge dedupes bg-*).
+    // No `invalid` key: a switch is binary — on and off are both valid values, so there is
+    // nothing to validate. (See §9 carve-out: invalid only applies to controls with a value.)
+    trackStates: {
+        unchecked: "bg-[var(--color-mono-200)] dark:bg-[var(--color-mono-700)]",
+        checked: "bg-[var(--color-primary)]",
+        disabled: "bg-[var(--color-background-disabled)] cursor-not-allowed",
+    },
+    // Thumb knob — soft elevation. OFF state: white gradient (it rides the neutral
+    // off-track, which is never white). ON state: Switch.tsx swaps the fill to
+    // --color-primary-contrast so the knob stays visible on any primary track — white
+    // on a dark primary, dark on a light primary (the near-white-primary case).
+    thumb: "rounded-full bg-gradient-to-b from-neutral-200 via-neutral-50 to-white shadow-real-lg border-t border-white/80 dark:border-white/20 transition-shadow duration-300 motion-reduce:transition-none",
     description: "text-sm text-[var(--color-text-muted)] -mt-1.5",
+    trackSizes: {
+        sm: "w-9 h-5",
+        md: "w-12 h-6",
+        lg: "w-14 h-7",
+    },
+    thumbSizes: {
+        sm: "w-5 h-4",
+        md: "w-7 h-5",
+        lg: "w-8 h-6",
+    },
 };
 /**
  * Thumb position values for animation
  */
 const thumbPositions = {
-    checked: { x: 18, y: 2 },
-    unchecked: { x: 2, y: 2 },
+    sm: {
+        checked: { x: 14, y: 2 },
+        unchecked: { x: 2, y: 2 },
+    },
+    md: {
+        checked: { x: 18, y: 2 },
+        unchecked: { x: 2, y: 2 },
+    },
+    lg: {
+        checked: { x: 22, y: 2 },
+        unchecked: { x: 2, y: 2 },
+    },
 };
 
 export { switchTheme, thumbPositions };

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

@@ -3,29 +3,53 @@
  */
 export type SwitchLabelPosition = "start" | "end";
 /**
- * State variants for the switch component
+ * State variants for the switch component.
+ *
+ * No `invalid`: a switch is binary — on and off are both valid values, so there is
+ * nothing to validate (unlike Input/Checkbox, which can hold/require a specific value).
  */
-export type SwitchState = 'default' | 'disabled' | 'invalid';
+export type SwitchState = 'default' | 'disabled';
+/**
+ * Size variants for the switch component
+ */
+export type SwitchSize = 'sm' | 'md' | 'lg';
+/**
+ * Resolvable visual states for the track. Layered additively in JS (see Switch.tsx)
+ * rather than via `data-[state=*]:` variants, so `className`/`theme` overrides win.
+ */
+export type SwitchTrackState = 'unchecked' | 'checked' | 'disabled';
 /**
  * Switch component props
  */
 export interface SwitchProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
-    /** Unique identifier for the switch input */
-    id: string;
+    /** Unique identifier for the switch input — if omitted, one is generated via React.useId() */
+    id?: string;
     /** Whether the switch is checked (controlled mode) */
     checked?: boolean;
+    /** Initial checked state for uncontrolled mode */
+    defaultChecked?: boolean;
     /** Function called when the switch state changes */
     onChange?: (checked: boolean) => void;
-    /** Label text for the switch */
-    label?: string;
-    /** Optional description text */
-    description?: string;
+    /** Label for the switch — pass a string for default styling, or a ReactNode for full control */
+    label?: React.ReactNode;
+    /** Optional description — pass a string for default styling, or a ReactNode for full control */
+    description?: React.ReactNode;
     /** The state of the switch (default, disabled, invalid) */
     state?: SwitchState;
     /** Position of the label relative to the switch */
     labelPosition?: SwitchLabelPosition;
+    /** Size of the switch track and thumb */
+    size?: SwitchSize;
     /** Optional theme overrides */
     theme?: SwitchThemeOverrides;
+    /** HTML name attribute for the hidden input */
+    name?: string;
+    /** HTML value attribute for the hidden input */
+    value?: string;
+    /** Whether the hidden input is required */
+    required?: boolean;
+    /** The id of the form this input belongs to */
+    form?: string;
 }
 /**
  * Switch theme configuration
@@ -33,8 +57,11 @@ export interface SwitchProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
 export interface SwitchTheme {
     container: string;
     track: string;
+    trackStates: Record<SwitchTrackState, string>;
     thumb: string;
     description: string;
+    trackSizes: Record<SwitchSize, string>;
+    thumbSizes: Record<SwitchSize, string>;
 }
 /**
  * Switch theme overrides
@@ -42,6 +69,7 @@ export interface SwitchTheme {
 export interface SwitchThemeOverrides {
     container?: string;
     track?: string;
+    trackStates?: Partial<Record<SwitchTrackState, string>>;
     thumb?: string;
     description?: string;
 }

package/dist/components/forms/Textarea/Textarea.js

@@ -1,10 +1,11 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useState } from 'react';
 import { FormLabel } from '../FormLabel/FormLabel.js';
 import { textareaTheme } from './Textarea.theme.js';
 import { cn } from '../../../utils/cn.js';
 
-const Textarea = React__default.forwardRef(({ size = "md", state = "default", className = "", label, labelClassName = "", helperText, helperTextClassName = "", wrapperClassName = "", inputGroupClassName = "", id, theme = {}, required, rows = 3, cols, unstyled = false, ...props }, ref) => {
+const Textarea = React__default.forwardRef(({ size = "md", state = "default", className = "", label, labelClassName = "", helperText, errorMessage, helperTextClassName = "", wrapperClassName = "", inputGroupClassName = "", id, theme = {}, required, rows = 3, cols, unstyled = false, onValueChange, ...props }, ref) => {
     var _a, _b, _c, _d;
     const [isFocused, setIsFocused] = useState(false);
     const generatedId = React__default.useId();
@@ -12,6 +13,9 @@ const Textarea = React__default.forwardRef(({ size = "md", state = "default", cl
     // Derived state flags for internal use
     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;
     // If unstyled, render only the textarea element
     if (unstyled) {
         return (jsx("textarea", { ref: ref, id: inputId, className: className, disabled: isDisabled, "aria-invalid": isInvalid, required: required, rows: rows, cols: cols, onFocus: (e) => {
@@ -30,6 +34,8 @@ const Textarea = React__default.forwardRef(({ size = "md", state = "default", cl
         : isDisabled
             ? "state-disabled"
             : "state-default";
+    // Pull onChange out of props so the explicit handler below isn't overwritten by the spread
+    const { onChange: propsOnChange, ...restProps } = props;
     // Get theme classes
     const wrapperClasses = theme.wrapperStyle || textareaTheme.wrapperStyle || "";
     const inputGroupClasses = theme.inputGroupStyle || textareaTheme.inputGroupStyle || "";
@@ -37,7 +43,7 @@ const Textarea = React__default.forwardRef(({ size = "md", state = "default", cl
     const sizeClasses = ((_a = theme.sizes) === null || _a === void 0 ? void 0 : _a[size]) || ((_b = textareaTheme.sizes) === null || _b === void 0 ? void 0 : _b[size]) || "";
     const stateClasses = ((_c = theme.states) === null || _c === void 0 ? void 0 : _c[state]) || ((_d = textareaTheme.states) === null || _d === void 0 ? void 0 : _d[state]) || "";
     const helperTextClasses = theme.helperText || textareaTheme.helperText || "";
-    return (jsxs("div", { className: cn(wrapperClasses, stateClass, wrapperClassName), children: [label && (jsx("div", { className: "mb-1", children: jsx(FormLabel, { htmlFor: inputId, className: labelClassName, state: state, required: required, children: label }) })), jsx("div", { children: jsx("div", { className: cn(inputGroupClasses, stateClasses, inputGroupClassName), children: jsx("div", { className: "relative flex-1", children: jsx("textarea", { ref: ref, id: inputId, className: cn(baseClasses, sizeClasses, className), disabled: isDisabled, "aria-invalid": isInvalid, required: required, rows: rows, cols: cols, onFocus: (e) => {
+    return (jsxs("div", { className: cn(wrapperClasses, stateClass, wrapperClassName), children: [label && (typeof label === 'string' ? (jsx("div", { className: "mb-1", children: jsx(FormLabel, { htmlFor: inputId, className: labelClassName, state: state, required: required, children: label }) })) : (label)), jsx("div", { children: jsx("div", { className: cn(inputGroupClasses, stateClasses, inputGroupClassName), children: jsx("div", { className: "relative flex-1", children: jsx("textarea", { ref: ref, id: inputId, className: cn(baseClasses, sizeClasses, className), disabled: isDisabled, "aria-invalid": isInvalid, "aria-describedby": displayedMessage ? `${inputId}-helper` : undefined, required: required, rows: rows, cols: cols, onFocus: (e) => {
                                 var _a;
                                 setIsFocused(true);
                                 (_a = props.onFocus) === null || _a === void 0 ? void 0 : _a.call(props, e);
@@ -45,7 +51,10 @@ const Textarea = React__default.forwardRef(({ size = "md", state = "default", cl
                                 var _a;
                                 setIsFocused(false);
                                 (_a = props.onBlur) === null || _a === void 0 ? void 0 : _a.call(props, e);
-                            }, ...props }) }) }) }), helperText && (jsx("div", { className: cn(helperTextClasses, helperTextClassName), children: helperText }))] }));
+                            }, onChange: (e) => {
+                                propsOnChange === null || propsOnChange === void 0 ? void 0 : propsOnChange(e);
+                                onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange(e.target.value);
+                            }, ...restProps }) }) }) }), displayedMessage && (typeof displayedMessage === 'string' ? (jsx("div", { id: `${inputId}-helper`, role: isInvalid ? "alert" : undefined, className: cn(helperTextClasses, helperTextClassName), children: displayedMessage })) : (displayedMessage))] }));
 });
 Textarea.displayName = "Textarea";
 

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

@@ -11,10 +11,16 @@ export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextArea
     size?: TextareaSize;
     /** The state of the textarea (default, disabled, invalid) */
     state?: TextareaState;
-    /** Optional label text for the textarea */
-    label?: string;
-    /** Optional helper text displayed below the textarea */
-    helperText?: string;
+    /** Optional label for the textarea — pass a string for default styling, or a ReactNode for full control */
+    label?: React.ReactNode;
+    /** Optional helper text below the textarea — 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;
     /** Additional class name for the textarea */
     className?: string;
     /** Additional class name for the label */
@@ -35,6 +41,8 @@ export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextArea
     cols?: number;
     /** Render only the textarea element without wrapper, label, or helper text */
     unstyled?: 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 TextareaSize = 'sm' | 'md' | 'lg';
 export type TextareaState = 'default' | 'disabled' | 'invalid';

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

@@ -1,16 +1,7 @@
 import React from "react";
 import { TimePickerProps } from "./TimePicker.types";
-interface TimePickerContextType {
-    isOpen: boolean;
-    setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
-    theme: ReturnType<typeof Object.assign>;
-    triggerRef: React.RefObject<HTMLDivElement | null>;
-    inputRef: React.RefObject<HTMLInputElement | null>;
-    hasValue: boolean;
-    size: "sm" | "md" | "lg";
-    state: "default" | "disabled" | "invalid";
-}
-export declare const TimePickerContext: React.Context<TimePickerContextType | undefined>;
+import { TimePickerContext } from "./TimePickerContext";
+export { TimePickerContext };
 /**
  * Main TimePicker Component
  *
@@ -23,4 +14,3 @@ export declare const TimePickerContext: React.Context<TimePickerContextType | un
  * - Validation with min/max time constraints
  */
 export declare const TimePicker: React.ForwardRefExoticComponent<TimePickerProps & React.RefAttributes<HTMLDivElement>>;
-export {};

package/dist/components/forms/TimePicker/TimePicker.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { createContext, useState, useRef, useMemo, useCallback, useEffect } from 'react';
+import React__default, { useState, useRef, useMemo, useCallback, useEffect } from 'react';
 import { FormLabel } from '../FormLabel/FormLabel.js';
 import { timePickerTheme } from './TimePicker.theme.js';
 import { cn } from '../../../utils/cn.js';
@@ -7,8 +8,8 @@ import { TimePickerTrigger } from './TimePickerTrigger.js';
 import { TimePickerContent } from './TimePickerContent.js';
 import { WheelColumn } from './WheelColumn.js';
 import { formatTimeInput, isValidTimeInput } from '../Input/inputMasks.js';
+import { TimePickerContext } from './TimePickerContext.js';
 
-const TimePickerContext = createContext(undefined);
 /**
  * Utility functions for time handling
  */
@@ -184,7 +185,7 @@ const get24Hour = (displayHour, period) => {
  */
 const TimePicker = React__default.forwardRef(({ value, defaultValue, onChange, format = "24h", step = 1, minTime, maxTime, disabled = false, placeholder = format === "12h"
     ? "HH:MM"
-    : "HH:MM", size = "md", state = "default", clearable = true, label, helperText, iconStart, iconEnd, className, labelClassName, helperTextClassName, theme = {}, id, ...props }, ref) => {
+    : "HH:MM", size = "md", state = "default", clearable = true, label, helperText, iconStart, iconEnd, className, labelClassName, helperTextClassName, theme = {}, id, elevation, lift, ...props }, ref) => {
     var _a;
     // Internal state
     const [isOpen, setIsOpen] = useState(false);
@@ -418,6 +419,7 @@ const TimePicker = React__default.forwardRef(({ value, defaultValue, onChange, f
         // Reset sync source after processing
         syncSourceRef.current = null;
     }, [pendingTime, format]);
+    const dialogId = `${inputId}-dialog`;
     // Context value
     const contextValue = useMemo(() => ({
         isOpen,
@@ -428,7 +430,8 @@ const TimePicker = React__default.forwardRef(({ value, defaultValue, onChange, f
         hasValue: Boolean(displayValue),
         size,
         state: finalState,
-    }), [isOpen, mergedTheme, displayValue, size, finalState]);
+        dialogId,
+    }), [isOpen, mergedTheme, displayValue, size, finalState, dialogId]);
     // Current period for trigger display
     const currentPeriod = (pendingTime === null || pendingTime === void 0 ? void 0 : pendingTime.period) || currentTime.period || (format === "12h" ? "AM" : undefined);
     // Compute the value shown in the input:
@@ -447,7 +450,7 @@ const TimePicker = React__default.forwardRef(({ value, defaultValue, onChange, f
                 else if (ref) {
                     ref.current = el;
                 }
-            }, className: cn(mergedTheme.containerStyle, className), children: [label && (jsx(FormLabel, { htmlFor: inputId, className: labelClassName, state: finalState, required: props.required, children: label })), jsx(TimePickerTrigger, { id: inputId, disabled: disabled, isOpen: isOpen, state: finalState, size: size, clearable: clearable, onClear: handleClear, iconStart: iconStart, iconEnd: iconEnd, inputValue: inputDisplayValue, onInputChange: handleInputChange, onInputFocus: handleInputFocus, onInputKeyDown: handleInputKeyDown, format: format, period: currentPeriod, onPeriodToggle: handlePeriodToggle, placeholder: placeholder }), jsxs(TimePickerContent, { isOpen: isOpen, onCancel: handleCancel, onSave: handleSave, portal: true, placement: "bottom-start", offset: 4, dropdownRef: dropdownRef, children: [jsx(WheelColumn, { label: "Hour", options: hourOptions, value: getDisplayHour(wheelTime.hour, format), onChange: handleHourChange, theme: mergedTheme }), jsx(WheelColumn, { label: "Min", options: minuteOptions, value: wheelTime.minute, onChange: handleMinuteChange, theme: mergedTheme }), format === "12h" && (jsx(WheelColumn, { label: "", options: periodOptions, value: wheelTime.period || "AM", onChange: handlePeriodChange, theme: mergedTheme }))] }), (helperText || validationError) && (jsx("p", { className: cn(mergedTheme.helperTextStyle, (_a = mergedTheme.helperTextStates) === null || _a === void 0 ? void 0 : _a[finalState], helperTextClassName), children: validationError || helperText }))] }) }));
+            }, className: cn(mergedTheme.containerStyle, className), children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: inputId, className: labelClassName, state: finalState, required: props.required, children: label })) : (label)), jsx(TimePickerTrigger, { id: inputId, disabled: disabled, isOpen: isOpen, state: finalState, size: size, clearable: clearable, onClear: handleClear, iconStart: iconStart, iconEnd: iconEnd, inputValue: inputDisplayValue, onInputChange: handleInputChange, onInputFocus: handleInputFocus, onInputKeyDown: handleInputKeyDown, format: format, period: currentPeriod, onPeriodToggle: handlePeriodToggle, placeholder: placeholder, "aria-invalid": finalState === 'invalid' || undefined, "aria-describedby": helperText ? `${inputId}-helper` : undefined }), jsxs(TimePickerContent, { isOpen: isOpen, onCancel: handleCancel, onSave: handleSave, portal: true, placement: "bottom-start", offset: 4, dropdownRef: dropdownRef, elevation: elevation, lift: lift, children: [jsx(WheelColumn, { label: "Hour", options: hourOptions, value: getDisplayHour(wheelTime.hour, format), onChange: handleHourChange, theme: mergedTheme }), jsx(WheelColumn, { label: "Min", options: minuteOptions, value: wheelTime.minute, onChange: handleMinuteChange, theme: mergedTheme }), format === "12h" && (jsx(WheelColumn, { label: "", options: periodOptions, value: wheelTime.period || "AM", onChange: handlePeriodChange, theme: mergedTheme }))] }), (helperText || validationError) && (typeof helperText === 'string' || validationError ? (jsx("p", { id: `${inputId}-helper`, className: cn(mergedTheme.helperTextStyle, (_a = mergedTheme.helperTextStates) === null || _a === void 0 ? void 0 : _a[finalState], helperTextClassName), children: validationError || helperText })) : (helperText))] }) }));
 });
 TimePicker.displayName = "TimePicker";
 

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

@@ -33,13 +33,12 @@ const timePickerTheme = {
     // Placeholder text style - matches Select/Combobox placeholder styling
     placeholderTextStyle: formsBaseTheme.placeholderStyle,
     // Selected value text style
-    valueTextStyle: "text-[var(--color-text-primary)] dark:text-[var(--color-neutral-200)]",
+    valueTextStyle: "text-[var(--color-text-primary)]",
     // Clear button styles (positioned between left content and right icon)
     clearButtonStyle: "absolute right-8 top-1/2 -translate-y-1/2 p-1 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors z-10",
     // Dropdown container styles (TimePicker-specific)
     // Width is controlled by trigger size via estimatedWidth parameter
-    dropdownStyle: "fixed z-[1000] bg-white border border-[var(--color-border)] rounded-[var(--form-radius)] shadow-lg overflow-hidden " +
-        "dark:bg-[var(--color-background-secondary)] ",
+    dropdownStyle: "fixed z-[1000] backdrop-blur-md border border-[var(--color-border)] rounded-[var(--form-radius)] shadow-lg overflow-hidden",
     // Dropdown size variants - primarily for internal spacing/padding
     dropdownSizes: {
         sm: "",
@@ -50,8 +49,8 @@ const timePickerTheme = {
     helperTextStyle: formsBaseTheme.helperText,
     // Helper text state variants
     helperTextStates: {
-        default: "text-[var(--color-text-muted)] dark:text-[var(--color-neutral-400)]",
-        disabled: "text-[var(--color-text-disabled)] dark:text-[var(--color-neutral-600)]",
+        default: "text-[var(--color-text-muted)]",
+        disabled: "text-[var(--color-text-disabled)]",
         invalid: "text-[var(--color-danger)] dark:text-[var(--color-danger-400)]",
     },
     // ============================================
@@ -70,18 +69,16 @@ const timePickerTheme = {
     // Wheel item active (selected) style - stronger text color and weight
     wheelItemActiveStyle: "text-[var(--color-text-primary)] font-semibold",
     // Footer container - flexbox for action buttons
-    footerStyle: "flex justify-between items-center gap-2 px-2 py-2 border-t border-[var(--color-border)] " +
-        "dark:border-[var(--color-neutral-700)]",
+    footerStyle: "flex justify-end items-center gap-2 px-2 py-2 border-t border-[var(--color-border)] ",
     // Inner input element style - transparent bg, no outline, tabular-nums for aligned digits
     inputStyle: "bg-transparent outline-none flex-1 tabular-nums min-w-0 " +
-        "text-[var(--color-text-primary)] placeholder:text-[var(--color-text-placeholder)] " +
-        "dark:text-[var(--color-neutral-200)] dark:placeholder:text-[var(--color-neutral-500)]",
+        "text-[var(--color-text-primary)] placeholder:text-[var(--color-text-placeholder)]",
     // AM/PM period toggle button
-    periodToggleStyle: "px-1.5 py-0.5 text-xs font-semibold rounded " +
-        "bg-[var(--color-background-tertiary)] text-[var(--color-text-primary)] " +
-        "hover:bg-[var(--color-background-quaternary)] transition-colors cursor-pointer select-none " +
-        "dark:bg-[var(--color-neutral-700)] dark:text-[var(--color-neutral-200)] " +
-        "dark:hover:bg-[var(--color-neutral-600)]",
+    periodToggleStyle: "px-1.5 py-0.5 text-xs font-semibold rounded-md " +
+        "bg-[var(--color-surface-sunken)] text-[var(--color-text-primary)] " +
+        "hover:bg-[var(--color-surface-hover)] transition-colors cursor-pointer select-none " +
+        "dark:bg-[var(--color-mono-700)] " +
+        "dark:hover:bg-[var(--color-mono-600)]",
 };
 
 export { timePickerTheme };

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 /**
  * TimePicker component props
  * @property {string} value - The selected time value in "HH:mm" format
@@ -44,9 +45,9 @@ export interface TimePickerProps extends Omit<React.InputHTMLAttributes<HTMLInpu
     /** Whether to show a clear button */
     clearable?: boolean;
     /** Optional label text */
-    label?: string;
+    label?: React.ReactNode;
     /** Optional helper text */
-    helperText?: string;
+    helperText?: React.ReactNode;
     /** Icon to display at the start (left side) */
     iconStart?: React.ReactNode;
     /** Icon to display at the end (right side) */
@@ -59,6 +60,13 @@ export interface TimePickerProps extends Omit<React.InputHTMLAttributes<HTMLInpu
     helperTextClassName?: string;
     /** Component-level theme overrides */
     theme?: TimePickerThemeOverrides;
+    /**
+     * Pin the dropdown surface elevation rung (overrides the automatic relative lift).
+     * A rung number (1–8) or a semantic alias ("surface"/"raised"/"overlay"…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the dropdown's base rung. */
+    lift?: boolean;
 }
 /**
  * Time display format options
@@ -175,6 +183,10 @@ export interface TimePickerTriggerProps {
     id?: string;
     /** Whether the trigger is disabled */
     disabled?: boolean;
+    /** Whether the trigger has an invalid value */
+    "aria-invalid"?: boolean;
+    /** ID of the element that describes the trigger */
+    "aria-describedby"?: string;
     /** Whether the dropdown is open */
     isOpen?: boolean;
     /** Visual state of the trigger */
@@ -254,4 +266,11 @@ export interface TimePickerContentProps {
     children?: React.ReactNode;
     /** Ref to the dropdown element (for portal-aware click-outside detection) */
     dropdownRef?: React.RefObject<HTMLDivElement | null>;
+    /**
+     * Pin the dropdown surface elevation rung (overrides the automatic relative lift).
+     * A rung number (1–8) or a semantic alias ("surface"/"raised"/"overlay"…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the dropdown's base rung. */
+    lift?: boolean;
 }