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

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

@@ -38,8 +38,7 @@ const timePickerTheme = {
     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: "",
@@ -70,17 +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)]",
     // 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)] " +
+    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-neutral-700)] " +
         "dark:hover:bg-[var(--color-neutral-600)]",
 };
 

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;
 }

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

@@ -1,119 +1,17 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { useContext, useCallback, useState, useEffect } from 'react';
+import { useContext, useCallback } from 'react';
 import { AnimatePresence, motion } from 'motion/react';
 import { createPortal } from 'react-dom';
 import { cn } from '../../../utils/cn.js';
-import { TimePickerContext } from './TimePicker.js';
+import { TimePickerContext } from './TimePickerContext.js';
 import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { createDropdownAnimations } from '../Select/Select.animations.js';
-import '../../core/Accordion/Accordion.js';
-import '../../core/AlertDialog/AlertDialog.js';
-import '../../core/AspectRatio/AspectRatio.js';
-import '../../core/Avatar/Avatar.js';
-import '../../core/AvatarGroup/AvatarGroup.js';
-import '../../core/Badge/Badge.js';
-import '../../core/Breadcrumbs/Breadcrumbs.js';
-import '../../core/Breadcrumbs/Breadcrumbs.theme.js';
 import { Button } from '../../core/Button/Button.js';
-import '../../core/ButtonGroup/ButtonGroup.js';
-import '../../core/ButtonGroup/ButtonGroupSeparator.js';
-import '../../core/ButtonGroup/ButtonGroupText.js';
-import '../../core/Calendar/Calendar.js';
-import '../../core/Calendar/CalendarMini/CalendarMini.js';
-import '../../core/Card/Card.js';
-import '../../core/CardStack/CardStack.js';
-import '../../core/Carousel/Carousel.js';
-import '../../core/CommandPalette/CommandPalette.js';
-import '../../core/Separator/Separator.js';
-import '../../core/Drawer/Drawer.js';
-import '../../core/Dropdown/Dropdown.js';
-import '../../core/Dropdown/DropdownTrigger.js';
-import '../../core/Dropdown/DropdownMenu.js';
-import '../../core/Dropdown/DropdownItem.js';
-import '../../core/Dropdown/DropdownSection.js';
-import '../../core/Dropdown/DropdownSeparator.js';
-import '../../core/Dropdown/Dropdown.theme.js';
-import '../../core/Kbd/Kbd.js';
-import '../../core/MenuItem/MenuItem.js';
-import '../../core/Link/Link.js';
-import '../../core/Loader/Loader.js';
-import '../../core/Modal/Modal.js';
-import '../../core/ModalStack/ModalStack.js';
-import '../../core/PageHeading/PageHeading.js';
-import '../../core/Pagination/Pagination.js';
-import '../../core/Popover/Popover.js';
-import '../../core/Popover/PopoverContext.js';
-import '../../core/Progress/Progress.js';
-import '../../core/Rating/Rating.js';
-import '../../core/ScrollArea/ScrollArea.js';
-import '../../core/ScrollArea/smooth/SmoothScrollEngine.js';
-import '../../core/Segmented/Segmented.js';
-import '../../core/Skeleton/Skeleton.js';
-import '../../core/SlidingNumber/SlidingNumber.js';
-import '../../core/Tabs/Tabs.js';
-import '../../core/Tabs/TabsList.js';
-import '../../core/Tabs/TabsTrigger.js';
-import '../../core/Tabs/TabsContent.js';
-import '../../core/Tabs/TabsContext.js';
-import '../../core/Tooltip/Tooltip.js';
-import '../../core/Tooltip/Tooltip.animations.js';
-import '../../core/Tree/Tree.js';
-import '../../core/Tag/Tag.js';
-import '../../core/Alert/Alert.js';
-import '../../core/Toast/Toast.js';
-import '../../core/Toast/ToastProvider.js';
-import '@heroicons/react/24/solid';
-import '../../core/Spinner/Spinner.js';
-import '../../core/Message/Message.js';
-import '../../core/Message/TypeWriter.js';
-import '../../core/Empty/Empty.js';
-import '../../core/Masonry/Masonry.js';
-import '../../core/DragDrop/DragDrop.js';
-import '../../core/Sortable/Sortable.js';
-import '../../core/NavItem/NavItem.js';
-import '../../core/Sidebar/Sidebar.js';
-import '../../core/Sidebar/SidebarHeader.js';
-import '../../core/Sidebar/SidebarContent.js';
-import '../../core/Sidebar/SidebarFooter.js';
-import '../../core/Sidebar/SidebarNav.js';
-import '../../core/Sidebar/SidebarNavGroup.js';
-import '../../core/Sidebar/SidebarToggle.js';
-import '../../core/Sidebar/SidebarContext.js';
-import '../../core/OfflineIndicator/OfflineIndicator.js';
-import '../../core/ContextMenu/ContextMenu.js';
-import '../../core/ContextMenu/ContextMenu.theme.js';
-import '../../core/Pill/Pill.js';
-import '../../core/SocialIcon/SocialIcon.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
-/**
- * Hook to detect dark mode state from document
- */
-const useDarkMode = () => {
-    const [isDark, setIsDark] = useState(false);
-    useEffect(() => {
-        if (typeof document === "undefined")
-            return;
-        const checkDarkMode = () => {
-            const hasDarkClass = document.documentElement.classList.contains("dark") ||
-                document.body.classList.contains("dark") ||
-                document.querySelector(".dark") !== null;
-            setIsDark(hasDarkClass);
-        };
-        checkDarkMode();
-        const observer = new MutationObserver(checkDarkMode);
-        observer.observe(document.documentElement, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        observer.observe(document.body, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        return () => observer.disconnect();
-    }, []);
-    return isDark;
-};
 /**
  * TimePickerContent Component - contains the time selector dropdown
  * Uses portal positioning like Select and DatePicker components
@@ -123,13 +21,16 @@ const useDarkMode = () => {
  * - Wheel column children (passed as children)
  * - Footer with Cancel and Save buttons
  */
-const TimePickerContent = ({ isOpen, onCancel, onSave, portal = true, placement = "bottom-start", offset = 4, children, dropdownRef, }) => {
+const TimePickerContent = ({ isOpen, onCancel, onSave, portal = true, placement = "bottom-start", offset = 4, children, dropdownRef, elevation, lift, }) => {
     var _a, _b;
+    // Relative elevation: the dropdown lifts above its host surface (overlay base = 5)
+    // so a TimePicker inside a Popover/Modal still reads as a higher plane.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const context = useContext(TimePickerContext);
     if (!context) {
         throw new Error("TimePickerContent must be used within a TimePicker");
     }
-    const { theme, triggerRef, size } = context;
+    const { theme, triggerRef, size, dialogId } = context;
     // Detect dark mode for portal content
     const isDarkMode = useDarkMode();
     const isClient = useIsClient();
@@ -170,7 +71,7 @@ const TimePickerContent = ({ isOpen, onCancel, onSave, portal = true, placement
             onSave();
         }
     }, [onCancel, onSave]);
-    const contentElement = (jsx(AnimatePresence, { mode: "wait", children: isOpen && (jsxs(motion.div, { ref: combinedRef, className: cn(theme.dropdownStyle, (_b = theme.dropdownSizes) === null || _b === void 0 ? void 0 : _b[size]), style: {
+    const contentElement = (jsx(AnimatePresence, { mode: "wait", children: isOpen && (jsx(motion.div, { ref: combinedRef, id: dialogId, className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), theme.dropdownStyle, (_b = theme.dropdownSizes) === null || _b === void 0 ? void 0 : _b[size]), style: {
                 ...cssVariables,
                 overscrollBehavior: "contain",
                 ...(portal
@@ -180,10 +81,10 @@ const TimePickerContent = ({ isOpen, onCancel, onSave, portal = true, placement
                         minWidth: `${position.width}px`,
                     }
                     : {}),
-            }, variants: animations, initial: "initial", animate: "visible", exit: "exit", onKeyDown: handleKeyDown, role: "dialog", "aria-modal": "true", "aria-label": "Select time", children: [jsx("div", { className: cn(theme.wheelContainerStyle), style: { height: 200 }, children: children }), jsxs("div", { className: cn(theme.footerStyle), children: [jsx(Button, { size: "sm", variant: "outline", color: "neutral", onClick: onCancel, "aria-label": "Cancel time selection", className: "flex-1", children: "Cancel" }), jsx(Button, { size: "sm", onClick: onSave, "aria-label": "Save selected time", className: "flex-1", children: "Save" })] })] })) }));
+            }, variants: animations, initial: "initial", animate: "visible", exit: "exit", onKeyDown: handleKeyDown, role: "dialog", "aria-modal": "true", "aria-label": "Select time", children: jsxs(SurfaceProvider, { level: surfaceLevel, children: [jsx("div", { className: cn(theme.wheelContainerStyle), style: { height: 200 }, children: children }), jsxs("div", { className: cn(theme.footerStyle), children: [jsx(Button, { size: "sm", variant: "outline", color: "neutral", onClick: onCancel, "aria-label": "Cancel time selection", className: "flex-1", children: "Cancel" }), jsx(Button, { size: "sm", onClick: onSave, "aria-label": "Save selected time", className: "flex-1", children: "Save" })] })] }) })) }));
     // Use portal if enabled and client-side - wrap with dark class for dark mode support
     return portal && isClient
-        ? createPortal(jsx("div", { className: isDarkMode ? "dark" : undefined, children: contentElement }), document.body)
+        ? createPortal(jsx("div", { "data-flikkui-portal": "", className: isDarkMode ? "dark" : undefined, children: contentElement }), document.body)
         : contentElement;
 };
 

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

@@ -0,0 +1,15 @@
+import React from "react";
+export 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";
+    /** id applied to the wheel-picker dialog — satisfies role="combobox"'s required aria-controls */
+    dialogId: string;
+}
+export declare const TimePickerContext: React.Context<TimePickerContextType | undefined>;
+export declare const useTimePickerContext: () => TimePickerContextType;

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

@@ -0,0 +1,6 @@
+"use client";
+import { createContext } from 'react';
+
+const TimePickerContext = createContext(undefined);
+
+export { TimePickerContext };

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

@@ -1,21 +1,22 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { useContext } from 'react';
 import { ClockIcon, XMarkIcon, ChevronUpDownIcon } from '@heroicons/react/24/outline';
 import { cn } from '../../../utils/cn.js';
-import { TimePickerContext } from './TimePicker.js';
+import { TimePickerContext } from './TimePickerContext.js';
 
 /**
  * TimePickerTrigger Component - combobox-style masked input
  * Displays a masked time input that opens the wheel picker on focus
  * Follows the same visual pattern as DatePickerTrigger and SelectButton
  */
-const TimePickerTrigger = ({ id, disabled, isOpen, state = 'default', size = 'md', clearable, onClear, iconStart, iconEnd, className, inputValue, onInputChange, onInputFocus, onInputKeyDown, format, period, onPeriodToggle, placeholder, }) => {
+const TimePickerTrigger = ({ id, disabled, isOpen, state = 'default', size = 'md', clearable, onClear, iconStart, iconEnd, className, inputValue, onInputChange, onInputFocus, onInputKeyDown, format, period, onPeriodToggle, placeholder, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedby, }) => {
     var _a, _b, _c, _d;
     const context = useContext(TimePickerContext);
     if (!context) {
         throw new Error('TimePickerTrigger must be used within a TimePicker');
     }
-    const { theme, triggerRef, inputRef, hasValue } = context;
+    const { theme, triggerRef, inputRef, hasValue, setIsOpen, dialogId } = context;
     const baseStyle = theme.baseStyle || "";
     const sizeStyle = ((_a = theme.triggerSizes) === null || _a === void 0 ? void 0 : _a[size]) || "";
     const stateStyle = ((_b = theme.triggerStates) === null || _b === void 0 ? void 0 : _b[state]) || "";
@@ -25,13 +26,26 @@ const TimePickerTrigger = ({ id, disabled, isOpen, state = 'default', size = 'md
     const periodToggleStyle = theme.periodToggleStyle || "";
     // Apply focused styles when open — same pattern as SelectButton and DatePickerTrigger
     const activeFocusState = isOpen
-        ? ((_d = theme.triggerFocusStates) === null || _d === void 0 ? void 0 : _d[state]) || "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"
+        ? ((_d = theme.triggerFocusStates) === null || _d === void 0 ? void 0 : _d[state]) || "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"
         : "";
     // Determine whether start icon is present (for input padding)
     const hasStartIcon = iconStart !== undefined ? Boolean(iconStart) : true;
     const iconStartPadding = theme.iconStartPadding || "";
-    return (jsx("div", { ref: triggerRef, className: "relative w-full", children: jsxs("div", { className: cn(baseStyle, stateStyle, hoverStateStyle, activeFocusState, 'w-full items-center', className // User overrides take highest precedence
-            ), children: [jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: inputRef, id: id, type: "text", inputMode: "numeric", value: inputValue, onChange: (e) => onInputChange(e.target.value), onFocus: onInputFocus, onKeyDown: onInputKeyDown, placeholder: placeholder, maxLength: 5, disabled: disabled, className: cn(inputStyle, sizeStyle, hasStartIcon && iconStartPadding), "aria-expanded": isOpen, "aria-haspopup": "dialog", "aria-label": "Enter time", autoComplete: "off" }), iconStart !== undefined ? (iconStart && jsx("div", { className: iconStartStyle, children: iconStart })) : (jsx("div", { className: iconStartStyle, children: jsx(ClockIcon, { className: "h-4 w-4" }) }))] }), format === '12h' && (jsx("button", { type: "button", onClick: onPeriodToggle, disabled: disabled, className: cn(periodToggleStyle, "shrink-0"), "aria-label": `Toggle AM/PM, current: ${period}`, tabIndex: -1, children: period || 'AM' })), clearable && hasValue && !disabled && (jsx("button", { type: "button", onClick: (e) => {
+    return (jsx("div", { ref: triggerRef, className: "relative w-full", children: jsxs("div", { onPointerDown: (e) => {
+                var _a;
+                if (disabled)
+                    return;
+                const target = e.target;
+                // The AM/PM and clear buttons handle their own clicks; the input focuses
+                // natively. Clicking anywhere else in the field (chevron, padding, icon)
+                // redirects focus to the input, which opens the dropdown via onInputFocus.
+                if (target.closest("button") || target === inputRef.current)
+                    return;
+                e.preventDefault();
+                (_a = inputRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+                setIsOpen(true);
+            }, className: cn(baseStyle, stateStyle, hoverStateStyle, activeFocusState, 'w-full items-center', className // User overrides take highest precedence
+            ), children: [jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: inputRef, id: id, type: "text", inputMode: "numeric", value: inputValue, onChange: (e) => onInputChange(e.target.value), onFocus: onInputFocus, onKeyDown: onInputKeyDown, placeholder: placeholder, maxLength: 5, disabled: disabled, className: cn(inputStyle, sizeStyle, hasStartIcon && iconStartPadding), role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "dialog", "aria-controls": dialogId, "aria-label": "Enter time", "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedby, autoComplete: "off" }), iconStart !== undefined ? (iconStart && jsx("div", { className: iconStartStyle, children: iconStart })) : (jsx("div", { className: iconStartStyle, children: jsx(ClockIcon, { className: "h-4 w-4" }) }))] }), format === '12h' && (jsx("button", { type: "button", onClick: onPeriodToggle, disabled: disabled, className: cn(periodToggleStyle, "shrink-0"), "aria-label": `Toggle AM/PM, current: ${period}`, tabIndex: -1, children: period || 'AM' })), clearable && hasValue && !disabled && (jsx("button", { type: "button", onClick: (e) => {
                         e.stopPropagation();
                         onClear === null || onClear === void 0 ? void 0 : onClear();
                     }, className: "shrink-0 p-0.5 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors", "aria-label": "Clear time", tabIndex: -1, children: jsx(XMarkIcon, { className: "w-4 h-4" }) })), iconEnd !== undefined ? (iconEnd && (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)] dark:text-[var(--color-neutral-500)]", children: iconEnd }))) : (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)] dark:text-[var(--color-neutral-500)]", children: jsx(ChevronUpDownIcon, { className: "h-4 w-4" }) }))] }) }));

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

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { useCallback, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';

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

@@ -1,3 +1,4 @@
+"use client";
 import { useRef, useState, useCallback, useEffect } from 'react';
 
 /**

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

@@ -42,6 +42,7 @@ export declare const formsBaseTheme: {
         disabled: string;
         invalid: string;
     };
+    groupInvalidOverlayStyle: string;
     helperText: string;
     iconStyles: {
         left: string;