@flikk/ui 1.0.0-beta.2 → 1.0.0-beta.21

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

@@ -95,7 +95,7 @@ export interface ColorPickerContextValue {
     isOpen: boolean;
     setIsOpen: (open: boolean) => void;
     triggerRef: React.RefObject<HTMLElement>;
-    placement: string;
+    placement: import("../../../hooks/useSelectPortal").SelectPlacement;
     offset: number;
     showAlpha: boolean;
     showEyeDropper: boolean;
@@ -149,9 +149,9 @@ export interface ColorPickerTriggerProps extends Omit<React.InputHTMLAttributes<
     className?: string;
 }
 /**
- * ColorPickerContent props
+ * ColorPickerBody props
  */
-export interface ColorPickerContentProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface ColorPickerBodyProps extends React.HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode;
     className?: string;
     /**

package/dist/components/forms/ColorPicker/ColorPickerBody.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { ColorPickerBodyProps } from './ColorPicker.types';
+/**
+ * ColorPickerBody - Popover content wrapper following Dropdown/Select patterns
+ * Uses portal rendering and useSelectPortal for positioning
+ */
+export declare const ColorPickerBody: React.FC<ColorPickerBodyProps>;

package/dist/components/forms/ColorPicker/{ColorPickerContent.js → ColorPickerBody.js}

@@ -10,23 +10,23 @@ import { ColorPickerContext } from './ColorPicker.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
 
 /**
- * ColorPickerContent - Popover content wrapper following Dropdown/Select patterns
+ * ColorPickerBody - Popover content wrapper following Dropdown/Select patterns
  * Uses portal rendering and useSelectPortal for positioning
  */
-const ColorPickerContent = ({ children, className, portal = true, animation = true, ...rest }) => {
+const ColorPickerBody = ({ children, className, portal = true, animation = true, ...rest }) => {
     const context = useContext(ColorPickerContext);
     const contentRef = useRef(null);
     const shouldReduceMotion = useReducedMotion();
     const isClient = useIsClient();
     if (!context) {
-        throw new Error('ColorPickerContent must be used within a ColorPicker');
+        throw new Error('ColorPicker.Body must be used within a ColorPicker');
     }
     const { isOpen, setIsOpen, theme, triggerRef, placement, offset } = context;
     // Use positioning hook (same as Dropdown/Select)
     const { position, cssVariables } = useSelectPortal({
         triggerRef,
         isOpen: isOpen || false,
-        placement: placement,
+        placement,
         offset: offset || 4,
         autoWidth: false,
     });
@@ -52,8 +52,8 @@ const ColorPickerContent = ({ children, className, portal = true, animation = tr
         document.addEventListener('keydown', handleEscape);
         return () => document.removeEventListener('keydown', handleEscape);
     }, [isOpen, setIsOpen, triggerRef]);
-    // Extract DOM props to avoid type conflicts with Framer Motion
-    const { onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...domProps } = rest;
+    // Extract DOM event handler props that conflict with Framer Motion
+    const { onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, ...domProps } = rest;
     const content = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: contentRef, role: "dialog", "aria-label": "Color picker", className: cn('fixed z-50', theme.contentStyle, className), style: {
                 ...cssVariables,
                 top: `${position.top}px`,
@@ -70,6 +70,6 @@ const ColorPickerContent = ({ children, className, portal = true, animation = tr
         ? createPortal(content, document.body)
         : content;
 };
-ColorPickerContent.displayName = 'ColorPickerContent';
+ColorPickerBody.displayName = 'ColorPicker.Body';
 
-export { ColorPickerContent };
+export { ColorPickerBody };

package/dist/components/forms/ColorPicker/ColorPickerInput.js

@@ -45,7 +45,7 @@ const ColorPickerInput = ({ className, ...props }) => {
     };
     // Render different input types based on format
     if (format === "hex") {
-        return (jsx("div", { className: cn(theme.inputContainerStyle, className), ...props, children: jsx(Input, { type: "text", size: "sm", value: inputValue, onChange: handleChange, onBlur: handleBlur, onKeyDown: handleKeyDown, state: isInvalid ? "invalid" : "default", placeholder: "#000000", className: "flex-1 text-sm font-mono", "aria-label": "Hex color value" }) }));
+        return (jsx("div", { className: cn(theme.inputContainerStyle, className), ...props, children: jsx(Input, { type: "text", size: "sm", value: inputValue, onChange: handleChange, onBlur: handleBlur, onKeyDown: handleKeyDown, state: isInvalid ? "invalid" : "default", placeholder: "#000000", className: "flex-1 text-base font-mono", "aria-label": "Hex color value" }) }));
     }
     if (format === "rgb") {
         const rgb = hslToRgb(color.h, color.s, color.l);
@@ -56,21 +56,21 @@ const ColorPickerInput = ({ className, ...props }) => {
                             if (parsed)
                                 setColor(parsed);
                         }
-                    }, className: "flex-1 text-sm", "aria-label": "Red", placeholder: "R" }), jsx(Input, { type: "number", size: "sm", min: 0, max: 255, value: rgb.g, onChange: (e) => {
+                    }, className: "flex-1 text-base", "aria-label": "Red", placeholder: "R" }), jsx(Input, { type: "number", size: "sm", min: 0, max: 255, value: rgb.g, onChange: (e) => {
                         const newG = parseInt(e.target.value, 10);
                         if (!isNaN(newG) && newG >= 0 && newG <= 255) {
                             const parsed = parseColor(`rgb(${rgb.r}, ${newG}, ${rgb.b})`);
                             if (parsed)
                                 setColor(parsed);
                         }
-                    }, className: "flex-1 text-sm", "aria-label": "Green", placeholder: "G" }), jsx(Input, { type: "number", size: "sm", min: 0, max: 255, value: rgb.b, onChange: (e) => {
+                    }, className: "flex-1 text-base", "aria-label": "Green", placeholder: "G" }), jsx(Input, { type: "number", size: "sm", min: 0, max: 255, value: rgb.b, onChange: (e) => {
                         const newB = parseInt(e.target.value, 10);
                         if (!isNaN(newB) && newB >= 0 && newB <= 255) {
                             const parsed = parseColor(`rgb(${rgb.r}, ${rgb.g}, ${newB})`);
                             if (parsed)
                                 setColor(parsed);
                         }
-                    }, className: "flex-1 text-sm", "aria-label": "Blue", placeholder: "B" })] }));
+                    }, className: "flex-1 text-base", "aria-label": "Blue", placeholder: "B" })] }));
     }
     if (format === "hsl") {
         return (jsxs("div", { className: cn(theme.inputContainerStyle, "flex gap-2", className), ...props, children: [jsx(Input, { type: "number", size: "sm", min: 0, max: 360, value: Math.round(color.h), onChange: (e) => {
@@ -78,17 +78,17 @@ const ColorPickerInput = ({ className, ...props }) => {
                         if (!isNaN(newH) && newH >= 0 && newH <= 360) {
                             setColor({ ...color, h: newH });
                         }
-                    }, className: "flex-1 text-sm", "aria-label": "Hue", placeholder: "H" }), jsx(Input, { type: "number", size: "sm", min: 0, max: 100, value: Math.round(color.s), onChange: (e) => {
+                    }, className: "flex-1 text-base", "aria-label": "Hue", placeholder: "H" }), jsx(Input, { type: "number", size: "sm", min: 0, max: 100, value: Math.round(color.s), onChange: (e) => {
                         const newS = parseInt(e.target.value, 10);
                         if (!isNaN(newS) && newS >= 0 && newS <= 100) {
                             setColor({ ...color, s: newS });
                         }
-                    }, className: "flex-1 text-sm", "aria-label": "Saturation", placeholder: "S" }), jsx(Input, { type: "number", size: "sm", min: 0, max: 100, value: Math.round(color.l), onChange: (e) => {
+                    }, className: "flex-1 text-base", "aria-label": "Saturation", placeholder: "S" }), jsx(Input, { type: "number", size: "sm", min: 0, max: 100, value: Math.round(color.l), onChange: (e) => {
                         const newL = parseInt(e.target.value, 10);
                         if (!isNaN(newL) && newL >= 0 && newL <= 100) {
                             setColor({ ...color, l: newL });
                         }
-                    }, className: "flex-1 text-sm", "aria-label": "Lightness", placeholder: "L" })] }));
+                    }, className: "flex-1 text-base", "aria-label": "Lightness", placeholder: "L" })] }));
     }
     return null;
 };

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

@@ -4,7 +4,7 @@
  */
 export { ColorPicker, useColorPicker, ColorPickerContext } from './ColorPicker';
 export { ColorPickerTrigger } from './ColorPickerTrigger';
-export { ColorPickerContent } from './ColorPickerContent';
+export { ColorPickerBody } from './ColorPickerBody';
 export { ColorPicker2DCanvas } from './ColorPicker2DCanvas';
 export { ColorPickerSwatch } from './ColorPickerSwatch';
 export { ColorPickerSliders } from './ColorPickerSliders';
@@ -12,6 +12,6 @@ export { ColorPickerInput } from './ColorPickerInput';
 export { ColorPickerFormatSelector } from './ColorPickerFormatSelector';
 export { ColorPickerEyeDropper } from './ColorPickerEyeDropper';
 export { ColorPickerPresets } from './ColorPickerPresets';
-export type { ColorPickerProps, ColorPickerTriggerProps, ColorPickerContentProps, ColorPickerSwatchProps, ColorPickerSlidersProps, ColorPickerInputProps, ColorPickerFormatSelectorProps, ColorPickerEyeDropperProps, ColorPickerPresetsProps, ColorPickerContextValue, ColorPickerTheme, ColorPickerThemeOverrides, ColorFormat, ColorPickerSize, ColorPickerState, } from './ColorPicker.types';
+export type { ColorPickerProps, ColorPickerTriggerProps, ColorPickerBodyProps, ColorPickerSwatchProps, ColorPickerSlidersProps, ColorPickerInputProps, ColorPickerFormatSelectorProps, ColorPickerEyeDropperProps, ColorPickerPresetsProps, ColorPickerContextValue, ColorPickerTheme, ColorPickerThemeOverrides, ColorFormat, ColorPickerSize, ColorPickerState, } from './ColorPicker.types';
 export type { RGB, RGBA, HSL, HSLA, HSV, HSVA } from './colorUtils';
 export { hexToRgb, rgbToHex, rgbToHsl, hslToRgb, rgbToHsv, hsvToRgb, validateHex, validateRgb, parseColor, formatHex, formatRgb, formatHsl, } from './colorUtils';

package/dist/components/forms/Combobox/Combobox.js

@@ -95,7 +95,8 @@ const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offse
         return () => document.removeEventListener("mousedown", handleClickOutside);
     }, [isOpen, onClose, portal, contentRef, optionsRef, triggerRef]);
     // Theme can come from Select's theme (optionsContainerStyle) or Combobox's theme (dropdownStyle)
-    const dropdownStyle = theme.dropdownStyle ||
+    const comboboxThemeRef = theme;
+    const dropdownStyle = comboboxThemeRef.dropdownStyle ||
         theme.optionsContainerStyle ||
         comboboxTheme.dropdownStyle;
     const optionStyle = theme.optionStyle || comboboxTheme.optionStyle;
@@ -396,7 +397,8 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
                                             ? `${comboboxId}-option-${customFilteredOptions[highlightedIndex].id}`
                                             : undefined, "aria-autocomplete": "list", "aria-invalid": isInvalid, autoComplete: "off", className: cn(inputClasses, sizeClasses, iconStartPadding, showClearButton && "pr-8", inputClassName), value: searchValue, onChange: handleInputChange, onFocus: handleInputFocus, onKeyDown: handleKeyDown, placeholder: placeholder, disabled: isDisabled, required: required }), hasLeftIcon && (jsx("div", { className: theme.iconStartStyle, children: iconStart })), showClearButton && (jsx("button", { type: "button", className: theme.clearButtonStyle, onClick: handleClear, "aria-label": "Clear selection", tabIndex: -1, children: jsx(XMarkIcon, { className: theme.clearIconStyle }) }))] }) }), jsx(ComboboxOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), triggerRef: wrapperRef, portal: portal, placement: placement, offset: offset, emptyMessage: emptyMessage, className: dropdownClassName })] }), helperText && (jsx("p", { className: cn(helperTextClasses, helperTextStateClasses), children: helperText })), name && (jsx("input", { type: "hidden", name: name, value: value !== undefined ? String(value) : "" }))] }) }));
 };
-const Combobox = React__default.forwardRef(ComboboxInner);
-Combobox.displayName = "Combobox";
+const ComboboxForwarded = React__default.forwardRef(ComboboxInner);
+ComboboxForwarded.displayName = "Combobox";
+const Combobox = ComboboxForwarded;
 
 export { Combobox };

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

@@ -0,0 +1,3 @@
+import React from "react";
+import { CronInputProps } from "./CronInput.types";
+export declare const CronInput: React.ForwardRefExoticComponent<CronInputProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/forms/CronInput/CronInput.js

@@ -0,0 +1,107 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default, { useId, useState, useEffect, useMemo, useCallback } from 'react';
+import { cronInputTheme } from './CronInput.theme.js';
+import { parseCron, validateCron, cronToDescription, getNextRuns, CRON_PRESETS, getMinuteOptions, getHourOptions, getDayOfMonthOptions, getMonthOptions, getDayOfWeekOptions, formatNextRun, fieldsToCron } from './CronInput.utils.js';
+import { FormLabel } from '../FormLabel/FormLabel.js';
+import { cn } from '../../../utils/cn.js';
+import { CalendarIcon, ClockIcon } from '@heroicons/react/24/outline';
+
+const FieldSelect = ({ label, value, options, onChange, disabled, size = "md", className, }) => {
+    const theme = cronInputTheme;
+    return (jsxs("div", { className: theme.fieldGroupStyle, children: [jsx("label", { className: theme.fieldLabelStyle, children: label }), jsx("select", { value: value, onChange: (e) => onChange(e.target.value), disabled: disabled, className: cn(theme.fieldSelectStyle, theme.fieldSelectSizes[size], className), "aria-label": `Cron ${label.toLowerCase()} field`, children: options.map((option) => (jsx("option", { value: option.value, children: option.label }, option.value))) })] }));
+};
+// ============================================================================
+// Main CronInput Component
+// ============================================================================
+const CronInput = React__default.forwardRef(({ value: controlledValue, defaultValue = "* * * * *", onChange, showPresets = true, showDescription = true, showNextRuns = true, nextRunCount = 3, size = "md", mode = "both", className, theme: themeOverrides, disabled = false, label, ...props }, ref) => {
+    // Unique ID for accessibility
+    const generatedId = useId();
+    // Controlled vs uncontrolled state
+    const isControlled = controlledValue !== undefined;
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    const cronValue = isControlled ? controlledValue : internalValue;
+    // Active mode when mode="both"
+    const [activeMode, setActiveMode] = useState(mode === "both" ? "visual" : mode);
+    // Raw input state (tracks what user is typing, may be invalid temporarily)
+    const [rawInput, setRawInput] = useState(cronValue);
+    // Sync raw input when controlled value changes
+    useEffect(() => {
+        if (isControlled) {
+            setRawInput(controlledValue);
+        }
+    }, [controlledValue, isControlled]);
+    // Merge theme with overrides
+    const theme = useMemo(() => ({
+        ...cronInputTheme,
+        ...themeOverrides,
+    }), [themeOverrides]);
+    // Parse current cron value into fields
+    const fields = useMemo(() => parseCron(cronValue), [cronValue]);
+    // Validation state
+    const isValid = useMemo(() => validateCron(cronValue), [cronValue]);
+    // Human-readable description
+    const description = useMemo(() => (isValid ? cronToDescription(cronValue) : ""), [cronValue, isValid]);
+    // Next run times
+    const nextRuns = useMemo(() => (isValid && showNextRuns ? getNextRuns(cronValue, nextRunCount) : []), [cronValue, isValid, showNextRuns, nextRunCount]);
+    // Active preset detection
+    const activePreset = useMemo(() => { var _a, _b; return (_b = (_a = CRON_PRESETS.find((p) => p.value === cronValue)) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : null; }, [cronValue]);
+    // Memoized options
+    const minuteOptions = useMemo(() => getMinuteOptions(), []);
+    const hourOptions = useMemo(() => getHourOptions(), []);
+    const dayOfMonthOptions = useMemo(() => getDayOfMonthOptions(), []);
+    const monthOptions = useMemo(() => getMonthOptions(), []);
+    const dayOfWeekOptions = useMemo(() => getDayOfWeekOptions(), []);
+    // Update the cron value
+    const updateValue = useCallback((newCron) => {
+        if (!isControlled) {
+            setInternalValue(newCron);
+        }
+        setRawInput(newCron);
+        onChange === null || onChange === void 0 ? void 0 : onChange(newCron);
+    }, [isControlled, onChange]);
+    // Handle field change from visual builder
+    const handleFieldChange = useCallback((field, newFieldValue) => {
+        const newFields = { ...fields, [field]: newFieldValue };
+        const newCron = fieldsToCron(newFields);
+        updateValue(newCron);
+    }, [fields, updateValue]);
+    // Handle raw input change
+    const handleRawInputChange = useCallback((e) => {
+        const newRaw = e.target.value;
+        setRawInput(newRaw);
+        if (validateCron(newRaw)) {
+            if (!isControlled) {
+                setInternalValue(newRaw);
+            }
+            onChange === null || onChange === void 0 ? void 0 : onChange(newRaw);
+        }
+    }, [isControlled, onChange]);
+    // Handle raw input blur - commit value if valid
+    const handleRawInputBlur = useCallback(() => {
+        if (validateCron(rawInput)) {
+            updateValue(rawInput);
+        }
+        else {
+            // Reset to last valid value
+            setRawInput(cronValue);
+        }
+    }, [rawInput, cronValue, updateValue]);
+    // Handle preset click
+    const handlePresetClick = useCallback((presetValue) => {
+        if (disabled)
+            return;
+        updateValue(presetValue);
+    }, [disabled, updateValue]);
+    // Handle Enter key in raw input
+    const handleRawKeyDown = useCallback((e) => {
+        if (e.key === "Enter") {
+            handleRawInputBlur();
+        }
+    }, [handleRawInputBlur]);
+    const showVisual = mode === "visual" || (mode === "both" && activeMode === "visual");
+    const showRaw = mode === "raw" || (mode === "both" && activeMode === "raw");
+    return (jsxs("div", { ref: ref, className: cn(theme.baseStyle, className), role: "group", "aria-label": label || "Cron expression builder", ...props, children: [label && (jsx(FormLabel, { htmlFor: `${generatedId}-cron`, state: disabled ? "disabled" : "default", children: label })), mode === "both" && (jsxs("div", { className: "flex items-center gap-1.5", children: [jsxs("button", { type: "button", onClick: () => setActiveMode("visual"), disabled: disabled, className: cn(theme.modeToggleStyle, activeMode === "visual" && theme.modeToggleActiveStyle), "aria-pressed": activeMode === "visual", children: [jsx(CalendarIcon, { className: "w-3.5 h-3.5 mr-1", "aria-hidden": "true" }), "Visual"] }), jsxs("button", { type: "button", onClick: () => setActiveMode("raw"), disabled: disabled, className: cn(theme.modeToggleStyle, activeMode === "raw" && theme.modeToggleActiveStyle), "aria-pressed": activeMode === "raw", children: [jsx(ClockIcon, { className: "w-3.5 h-3.5 mr-1", "aria-hidden": "true" }), "Cron"] })] })), showPresets && (jsxs("div", { children: [jsx("div", { className: cn(theme.sectionHeadingStyle, "mb-1.5"), children: "Presets" }), jsx("div", { className: "flex flex-wrap gap-1.5", children: CRON_PRESETS.map((preset) => (jsx("button", { type: "button", onClick: () => handlePresetClick(preset.value), disabled: disabled, className: cn(theme.presetButtonStyle, activePreset === preset.value && theme.presetButtonActiveStyle), title: preset.description, "aria-pressed": activePreset === preset.value, children: preset.label }, preset.value))) })] })), showVisual && (jsxs("div", { className: theme.builderStyle, children: [jsx(FieldSelect, { label: "Minute", value: fields.minute, options: minuteOptions, onChange: (v) => handleFieldChange("minute", v), disabled: disabled, size: size }), jsx(FieldSelect, { label: "Hour", value: fields.hour, options: hourOptions, onChange: (v) => handleFieldChange("hour", v), disabled: disabled, size: size }), jsx(FieldSelect, { label: "Day of Month", value: fields.dayOfMonth, options: dayOfMonthOptions, onChange: (v) => handleFieldChange("dayOfMonth", v), disabled: disabled, size: size }), jsx(FieldSelect, { label: "Month", value: fields.month, options: monthOptions, onChange: (v) => handleFieldChange("month", v), disabled: disabled, size: size }), jsx(FieldSelect, { label: "Day of Week", value: fields.dayOfWeek, options: dayOfWeekOptions, onChange: (v) => handleFieldChange("dayOfWeek", v), disabled: disabled, size: size })] })), showRaw && (jsxs("div", { children: [jsx("div", { className: cn(theme.sectionHeadingStyle, "mb-1.5"), children: "Cron Expression" }), jsx("input", { type: "text", value: rawInput, onChange: handleRawInputChange, onBlur: handleRawInputBlur, onKeyDown: handleRawKeyDown, disabled: disabled, placeholder: "* * * * *", className: cn(theme.rawInputStyle, theme.rawInputSizes[size]), id: `${generatedId}-cron`, "aria-label": "Cron expression", "aria-invalid": !validateCron(rawInput), spellCheck: false, autoComplete: "off" }), !validateCron(rawInput) && rawInput !== cronValue && (jsx("div", { className: cn(theme.errorStyle, "mt-1"), children: "Invalid cron expression. Format: minute hour day month weekday" }))] })), showVisual && !showRaw && (jsxs("div", { className: "flex items-center gap-2", children: [jsx("span", { className: cn(theme.fieldLabelStyle, "shrink-0"), children: "Expression:" }), jsx("code", { className: cn("font-mono text-sm px-2 py-1 rounded-[var(--form-radius)]", "bg-[var(--color-background-secondary)] text-[var(--color-text-primary)]", "dark:bg-[var(--color-neutral-800)] dark:text-[var(--color-neutral-200)]"), children: cronValue })] })), showDescription && isValid && (jsxs("div", { className: theme.descriptionStyle, children: [jsx(ClockIcon, { className: "w-4 h-4 shrink-0", "aria-hidden": "true" }), jsx("span", { children: description })] })), showNextRuns && isValid && nextRuns.length > 0 && (jsxs("div", { className: theme.nextRunsStyle, children: [jsx("div", { className: cn(theme.sectionHeadingStyle, "mb-1"), children: "Next runs" }), nextRuns.map((date, index) => (jsxs("div", { className: theme.nextRunItemStyle, children: [jsx(CalendarIcon, { className: "w-3.5 h-3.5 shrink-0", "aria-hidden": "true" }), jsx("span", { children: formatNextRun(date) })] }, index)))] }))] }));
+});
+CronInput.displayName = "CronInput";
+
+export { CronInput };

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

@@ -0,0 +1,6 @@
+import { CronInputTheme } from "./CronInput.types";
+/**
+ * Default theme for the CronInput component
+ * Uses flat structure with CSS variable design tokens
+ */
+export declare const cronInputTheme: CronInputTheme;

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

@@ -0,0 +1,84 @@
+import { formsBaseTheme } from '../forms.theme.js';
+
+/**
+ * Default theme for the CronInput component
+ * Uses flat structure with CSS variable design tokens
+ */
+const cronInputTheme = {
+    // Outer wrapper
+    baseStyle: "relative w-full flex flex-col gap-3",
+    // Label
+    labelStyle: "text-base font-medium text-[var(--color-text-primary)] dark:text-[var(--color-neutral-200)]",
+    // Visual builder grid
+    builderStyle: "grid grid-cols-5 gap-2",
+    // Individual field group
+    fieldGroupStyle: "flex flex-col gap-1",
+    // Field label
+    fieldLabelStyle: "text-sm font-medium text-[var(--color-text-secondary)] dark:text-[var(--color-neutral-400)]",
+    // Select dropdown
+    fieldSelectStyle: "w-full rounded-[var(--form-radius)] outline outline-1 outline-[var(--color-border)] " +
+        "bg-white text-[var(--color-text-primary)] cursor-pointer transition-all " +
+        "focus:outline-2 focus:outline-[var(--color-primary-600)] focus:-outline-offset-1 " +
+        "focus:ring-4 focus:ring-[var(--color-primary)]/10 " +
+        "disabled:cursor-not-allowed disabled:bg-[var(--color-background-disabled)] disabled:text-[var(--color-text-disabled)] " +
+        "dark:bg-[var(--color-neutral-900)] dark:outline-[var(--color-neutral-700)] dark:text-[var(--color-neutral-200)] " +
+        "dark:focus:outline-[var(--color-primary-500)] dark:focus:ring-[var(--color-primary-500)]/20",
+    // Size variants for field selects
+    fieldSelectSizes: {
+        sm: `${formsBaseTheme.sizes.sm.text} ${formsBaseTheme.sizes.sm.padding} ${formsBaseTheme.sizes.sm.height}`,
+        md: `${formsBaseTheme.sizes.md.text} ${formsBaseTheme.sizes.md.padding} ${formsBaseTheme.sizes.md.height}`,
+        lg: `${formsBaseTheme.sizes.lg.text} ${formsBaseTheme.sizes.lg.padding} ${formsBaseTheme.sizes.lg.height}`,
+    },
+    // Raw input field
+    rawInputStyle: "w-full rounded-[var(--form-radius)] outline outline-1 outline-[var(--color-border)] " +
+        "bg-white text-[var(--color-text-primary)] font-mono transition-all " +
+        "placeholder:text-[var(--color-text-placeholder)] focus:outline-none " +
+        "focus:outline-2 focus:outline-[var(--color-primary-600)] focus:-outline-offset-1 " +
+        "focus:ring-4 focus:ring-[var(--color-primary)]/10 " +
+        "disabled:cursor-not-allowed disabled:bg-[var(--color-background-disabled)] disabled:text-[var(--color-text-disabled)] " +
+        "dark:bg-[var(--color-neutral-900)] dark:outline-[var(--color-neutral-700)] dark:text-[var(--color-neutral-200)] " +
+        "dark:focus:outline-[var(--color-primary-500)] dark:focus:ring-[var(--color-primary-500)]/20",
+    // Size variants for raw input
+    rawInputSizes: {
+        sm: `${formsBaseTheme.sizes.sm.text} ${formsBaseTheme.sizes.sm.padding} ${formsBaseTheme.sizes.sm.height}`,
+        md: `${formsBaseTheme.sizes.md.text} ${formsBaseTheme.sizes.md.padding} ${formsBaseTheme.sizes.md.height}`,
+        lg: `${formsBaseTheme.sizes.lg.text} ${formsBaseTheme.sizes.lg.padding} ${formsBaseTheme.sizes.lg.height}`,
+    },
+    // Mode toggle button
+    modeToggleStyle: "inline-flex items-center justify-center rounded-[var(--form-radius)] px-3 py-1.5 text-sm font-medium " +
+        "cursor-pointer transition-all outline outline-1 outline-[var(--color-border)] " +
+        "text-[var(--color-text-secondary)] bg-white hover:bg-[var(--color-background-secondary)] " +
+        "dark:bg-[var(--color-neutral-900)] dark:outline-[var(--color-neutral-700)] dark:text-[var(--color-neutral-400)] " +
+        "dark:hover:bg-[var(--color-neutral-800)]",
+    // Active mode toggle
+    modeToggleActiveStyle: "outline-[var(--color-primary)] bg-[var(--color-primary-50)] text-[var(--color-primary)] " +
+        "hover:bg-[var(--color-primary-50)] " +
+        "dark:outline-[var(--color-primary-500)] dark:bg-[var(--color-primary-500)]/10 dark:text-[var(--color-primary-400)] " +
+        "dark:hover:bg-[var(--color-primary-500)]/15",
+    // Preset button
+    presetButtonStyle: "inline-flex items-center rounded-[var(--form-radius)] px-2.5 py-1 text-sm font-medium " +
+        "cursor-pointer transition-all outline outline-1 outline-[var(--color-border)] " +
+        "text-[var(--color-text-secondary)] bg-white hover:bg-[var(--color-background-secondary)] " +
+        "hover:text-[var(--color-text-primary)] " +
+        "dark:bg-[var(--color-neutral-900)] dark:outline-[var(--color-neutral-700)] dark:text-[var(--color-neutral-400)] " +
+        "dark:hover:bg-[var(--color-neutral-800)] dark:hover:text-[var(--color-neutral-200)]",
+    // Active preset button
+    presetButtonActiveStyle: "outline-[var(--color-primary)] bg-[var(--color-primary-50)] text-[var(--color-primary)] " +
+        "hover:bg-[var(--color-primary-100)] " +
+        "dark:outline-[var(--color-primary-500)] dark:bg-[var(--color-primary-500)]/10 dark:text-[var(--color-primary-400)]",
+    // Human-readable description
+    descriptionStyle: "flex items-center gap-2 text-base text-[var(--color-text-muted)] " +
+        "dark:text-[var(--color-neutral-400)]",
+    // Next runs container
+    nextRunsStyle: "flex flex-col gap-1",
+    // Individual next run item
+    nextRunItemStyle: "flex items-center gap-2 text-sm text-[var(--color-text-muted)] " +
+        "dark:text-[var(--color-neutral-400)]",
+    // Section heading
+    sectionHeadingStyle: "text-sm font-medium text-[var(--color-text-secondary)] uppercase tracking-wide " +
+        "dark:text-[var(--color-neutral-400)]",
+    // Validation error
+    errorStyle: "text-sm text-[var(--color-danger)] dark:text-[var(--color-danger-400)]",
+};
+
+export { cronInputTheme };

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

@@ -0,0 +1,98 @@
+import React from "react";
+/**
+ * CronInput component props
+ * A visual cron expression builder that outputs standard cron syntax
+ */
+export interface CronInputProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** Controlled cron expression string, e.g. "0 9 * * 1" */
+    value?: string;
+    /** Default cron expression for uncontrolled usage */
+    defaultValue?: string;
+    /** Callback fired when the cron expression changes */
+    onChange?: (cronExpression: string) => void;
+    /** Whether to show preset schedule buttons */
+    showPresets?: boolean;
+    /** Whether to show the human-readable description */
+    showDescription?: boolean;
+    /** Whether to show upcoming execution times */
+    showNextRuns?: boolean;
+    /** Number of next run times to display (default: 3) */
+    nextRunCount?: number;
+    /** Size variant */
+    size?: CronInputSize;
+    /** Display mode: visual builder, raw string input, or both */
+    mode?: CronInputMode;
+    /** Additional class name (highest priority, shadcn pattern) */
+    className?: string;
+    /** Theme overrides for sub-component styling */
+    theme?: CronInputThemeOverrides;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+    /** Label text for the component */
+    label?: string;
+}
+export type CronInputSize = "sm" | "md" | "lg";
+export type CronInputMode = "visual" | "raw" | "both";
+/**
+ * Parsed cron fields
+ */
+export interface CronFields {
+    minute: string;
+    hour: string;
+    dayOfMonth: string;
+    month: string;
+    dayOfWeek: string;
+}
+/**
+ * Preset schedule definition
+ */
+export interface CronPreset {
+    label: string;
+    value: string;
+    description: string;
+}
+/**
+ * Theme structure for CronInput component
+ */
+export interface CronInputTheme {
+    /** Outer wrapper */
+    baseStyle: string;
+    /** Label text */
+    labelStyle: string;
+    /** Visual builder section */
+    builderStyle: string;
+    /** Individual field group (label + select) */
+    fieldGroupStyle: string;
+    /** Field label */
+    fieldLabelStyle: string;
+    /** Select dropdown for each field */
+    fieldSelectStyle: string;
+    /** Size variants for the select dropdowns */
+    fieldSelectSizes: Record<CronInputSize, string>;
+    /** Raw input field */
+    rawInputStyle: string;
+    /** Size variants for the raw input */
+    rawInputSizes: Record<CronInputSize, string>;
+    /** Mode toggle button */
+    modeToggleStyle: string;
+    /** Active mode toggle button */
+    modeToggleActiveStyle: string;
+    /** Preset button */
+    presetButtonStyle: string;
+    /** Active preset button */
+    presetButtonActiveStyle: string;
+    /** Human-readable description */
+    descriptionStyle: string;
+    /** Next runs container */
+    nextRunsStyle: string;
+    /** Individual next run time */
+    nextRunItemStyle: string;
+    /** Section heading style */
+    sectionHeadingStyle: string;
+    /** Validation error style */
+    errorStyle: string;
+}
+/**
+ * Theme overrides - all optional for partial customization
+ */
+export type CronInputThemeOverrides = Partial<CronInputTheme>;

package/dist/components/forms/CronInput/CronInput.utils.d.ts

@@ -0,0 +1,67 @@
+import { CronFields, CronPreset } from "./CronInput.types";
+export declare const MONTH_NAMES: readonly ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+export declare const MONTH_SHORT_NAMES: readonly ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export declare const DAY_NAMES: readonly ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+export declare const DAY_SHORT_NAMES: readonly ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+/**
+ * Preset cron schedules for common use cases
+ */
+export declare const CRON_PRESETS: CronPreset[];
+export interface FieldOption {
+    value: string;
+    label: string;
+}
+/**
+ * Generate minute options: every minute (*), specific minutes, and intervals
+ */
+export declare function getMinuteOptions(): FieldOption[];
+/**
+ * Generate hour options: every hour (*), specific hours, and intervals
+ */
+export declare function getHourOptions(): FieldOption[];
+/**
+ * Generate day-of-month options: every day (*), specific days
+ */
+export declare function getDayOfMonthOptions(): FieldOption[];
+/**
+ * Generate month options: every month (*), specific months
+ */
+export declare function getMonthOptions(): FieldOption[];
+/**
+ * Generate day-of-week options: every day (*), specific days, ranges
+ */
+export declare function getDayOfWeekOptions(): FieldOption[];
+/**
+ * Parse a cron expression string into individual fields
+ */
+export declare function parseCron(expr: string): CronFields;
+/**
+ * Convert CronFields back to a cron expression string
+ */
+export declare function fieldsToCron(fields: CronFields): string;
+/**
+ * Validate a complete cron expression
+ */
+export declare function validateCron(expr: string): boolean;
+/**
+ * Convert a cron expression to a human-readable description
+ */
+export declare function cronToDescription(expr: string): string;
+/**
+ * Calculate the next N run times for a cron expression.
+ * Uses a brute-force minute-by-minute scan (simple approach for common cases).
+ *
+ * @param expr - Cron expression string
+ * @param count - Number of next runs to find (default: 3)
+ * @param from - Starting date (default: now)
+ * @returns Array of Date objects for the next runs
+ */
+export declare function getNextRuns(expr: string, count?: number, from?: Date): Date[];
+/**
+ * Format a Date as a human-readable next run string
+ */
+export declare function formatNextRun(date: Date): string;
+/**
+ * Check if a field value represents a specific number (not a pattern)
+ */
+export declare function isSpecificValue(value: string): boolean;