@aic-kits/react 0.34.7 → 0.34.11

package/dist/components/DatePicker/utils.d.ts

@@ -0,0 +1,203 @@
+import { DateConfig, DatePickerValue, WeekStartDay, TimezoneOption, TimeValue } from './types';
+/**
+ * Get the first day of the month
+ */
+export declare function getFirstDayOfMonth(date: Date): Date;
+/**
+ * Get the last day of the month
+ */
+export declare function getLastDayOfMonth(date: Date): Date;
+/**
+ * Add months to a date
+ */
+export declare function addMonths(date: Date, months: number): Date;
+/**
+ * Add days to a date
+ */
+export declare function addDays(date: Date, days: number): Date;
+/**
+ * Check if two dates are the same day
+ */
+export declare function isSameDay(date1: Date | null, date2: Date | null): boolean;
+/**
+ * Check if two dates are in the same month
+ */
+export declare function isSameMonth(date1: Date, date2: Date): boolean;
+/**
+ * Check if a date is today
+ */
+export declare function isToday(date: Date): boolean;
+/**
+ * Check if date is before another date (day comparison)
+ */
+export declare function isBefore(date: Date, compareDate: Date): boolean;
+/**
+ * Check if date is after another date (day comparison)
+ */
+export declare function isAfter(date: Date, compareDate: Date): boolean;
+/**
+ * Check if a year is a leap year
+ */
+export declare function isLeapYear(year: number): boolean;
+/**
+ * Get the number of days in a given month
+ * @param month 1-indexed month (1 = January, 12 = December)
+ * @param year Full year (e.g., 2024)
+ */
+export declare function getDaysInMonth(month: number, year: number): number;
+/**
+ * Get the starting date for the calendar grid (may be in previous month)
+ */
+export declare function getCalendarGridStartDate(month: Date, weekStartDay: WeekStartDay): Date;
+/**
+ * Generate calendar grid dates (6 weeks x 7 days = 42 days)
+ */
+export declare function generateCalendarGrid(month: Date, weekStartDay: WeekStartDay): Date[];
+/**
+ * Get weekday names starting from the specified day
+ */
+export declare function getWeekdayNames(locale: string, weekStartDay: WeekStartDay, format?: 'narrow' | 'short' | 'long'): string[];
+/**
+ * Check if a date is disabled based on configuration
+ */
+export declare function isDateDisabled(date: Date, config?: DateConfig): boolean;
+/**
+ * Check if an entire month is before/after date constraints
+ */
+export declare function isMonthDisabled(month: Date, direction: 'prev' | 'next', config?: DateConfig): boolean;
+/**
+ * Parse time string (HH:mm) to minutes from midnight
+ */
+export declare function parseTimeToMinutes(time: string): number;
+/**
+ * Format minutes from midnight to time string
+ */
+export declare function formatMinutesToTime(minutes: number, format?: '12h' | '24h'): string;
+/**
+ * Format date for display in header (e.g., "December 2024")
+ */
+export declare function formatMonthYear(date: Date, locale: string): string;
+/**
+ * Format month only (e.g., "December")
+ */
+export declare function formatMonth(date: Date, locale: string): string;
+/**
+ * Format year only (e.g., "2024")
+ */
+export declare function formatYear(date: Date): string;
+/**
+ * Get all month names for a locale
+ */
+export declare function getMonthNames(locale: string): string[];
+/**
+ * Get year range for year picker (12 years centered on current year)
+ */
+export declare function getYearRange(year: number): number[];
+/**
+ * Add years to a date
+ */
+export declare function addYears(date: Date, years: number): Date;
+/**
+ * Format date for selected date display (e.g., "Monday, July 22")
+ */
+export declare function formatSelectedDate(date: Date | null, locale: string): string;
+/**
+ * Format date for input display (e.g., "Dec 25, 2024 at 10:00am")
+ */
+export declare function formatDateTimeForInput(date: Date | null, locale: string): string;
+/**
+ * Format time value to string
+ */
+export declare function formatTimeValue(time: TimeValue | null, format?: '12h' | '24h'): string;
+/**
+ * Format date for editable input
+ * Always uses DD/MM/YYYY format for consistency with validation
+ * Optionally includes time if showTime is true
+ */
+export declare function formatDateForInput(date: Date | null, _locale: string, time?: TimeValue | null, showTime?: boolean, timeFormat?: '12h' | '24h'): string;
+/**
+ * Parse result from parseInputDateTime
+ */
+export interface ParsedDateTime {
+    date: Date;
+    time: TimeValue | null;
+}
+/**
+ * Parse user input string to Date and optional time
+ * Supports formats:
+ * - DD/MM/YYYY HH:mm (date with time suffix)
+ * - DD/MM/YYYY h:mm AM/PM (date with 12h time suffix)
+ * - DD/MM/YYYY or MM/DD/YYYY (date only)
+ * - YYYY-MM-DD (ISO date only)
+ * Returns null if parsing fails
+ */
+export declare function parseInputDateTime(input: string, locale: string): ParsedDateTime | null;
+/**
+ * Legacy function for backwards compatibility - parses date only
+ */
+export declare function parseInputDate(input: string, locale: string): Date | null;
+/**
+ * Get placeholder format based on locale and time format
+ * @param locale - locale for date format
+ * @param includeTime - if true, includes time placeholder
+ * @param timeFormat - '12h' or '24h' for time format
+ */
+export declare function getDateInputPlaceholder(_locale: string, includeTime?: boolean, timeFormat?: '12h' | '24h'): string;
+/**
+ * Get timezone offset string (e.g., "GMT-5")
+ */
+export declare function getTimezoneOffset(timezone: string): string;
+export declare function generateTimezoneOptions(): TimezoneOption[];
+/**
+ * Convert a date+time from one timezone to another
+ * Returns new Date and TimeValue in target timezone
+ *
+ * Example: 9:00 UTC on Jan 17 → 16:00 UTC+7 on Jan 17
+ */
+export declare function convertDateTimeToTimezone(date: Date, time: TimeValue, fromTimezone: string | null, toTimezone: string | null): {
+    date: Date;
+    time: TimeValue;
+};
+/**
+ * Convert a DatePickerValue to a different timezone
+ */
+export declare function convertSlotToTimezone(slot: DatePickerValue, toTimezone: string | null): DatePickerValue;
+/**
+ * Convert all slots to target timezone
+ */
+export declare function convertSlotsToTimezone(slots: DatePickerValue[], toTimezone: string | null): DatePickerValue[];
+/**
+ * Get all unique dates from slots array
+ */
+export declare function getDatesFromSlots(slots: DatePickerValue[]): Date[];
+/**
+ * Get time slots available for a specific date
+ */
+export declare function getTimeSlotsForDate(slots: DatePickerValue[], date: Date | null): TimeValue[];
+/**
+ * Check if a date has any available slots
+ */
+export declare function dateHasSlots(slots: DatePickerValue[], date: Date): boolean;
+/**
+ * Get all unique time slots from slots array (when no date is selected)
+ * Used to show preview of available times before user selects a date
+ */
+export declare function getAllUniqueTimeSlots(slots: DatePickerValue[]): TimeValue[];
+/**
+ * Create a DateConfig that disables dates without slots
+ */
+export declare function createSlotsDateConfig(slots: DatePickerValue[], existingConfig?: DateConfig): DateConfig;
+/**
+ * Convert DatePickerValue to timestamp (milliseconds) for comparison
+ * Combines date and time into single comparable number
+ */
+export declare function datePickerValueToTimestamp(value: DatePickerValue): number;
+/**
+ * Compare two DatePickerValues
+ * Returns:
+ *   -1 if a < b
+ *    0 if a === b
+ *    1 if a > b
+ *   null if either value has no date (incomparable)
+ */
+export declare function compareDatePickerValues(a: DatePickerValue | undefined, b: DatePickerValue | undefined): -1 | 0 | 1 | null;

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

@@ -38,6 +38,14 @@ interface BaseInputProps {
      * Icon to display on the right side of the input
      */
     rightIcon?: Icon;
+    /**
+     * Show clear button when input has value
+     */
+    clearable?: boolean;
+    /**
+     * Callback when clear button is clicked
+     */
+    onClear?: () => void;
     /**
      * Border color when focused
      */

package/dist/components/Select/SelectDropdown.d.ts

@@ -1,7 +1,7 @@
 import { SelectSize } from '../../theme/components/select';
 import { SelectOption } from './types';
 interface SelectDropdownProps<T extends string | number> {
-    anchorElement: HTMLElement;
+    anchorRef: React.RefObject<HTMLDivElement | null>;
     isOpen: boolean;
     options: SelectOption<T>[];
     onSelect: (option: SelectOption<T>) => void;
@@ -10,5 +10,5 @@ interface SelectDropdownProps<T extends string | number> {
     size: SelectSize;
     borderRadius: string;
 }
-export declare function SelectDropdown<T extends string | number>({ anchorElement, isOpen, options, onSelect, selectedValue, onClose, size, borderRadius, }: SelectDropdownProps<T>): import('react').ReactPortal | null;
+export declare function SelectDropdown<T extends string | number>({ anchorRef, isOpen, options, onSelect, selectedValue, onClose, size, borderRadius, }: SelectDropdownProps<T>): import("react/jsx-runtime").JSX.Element | null;
 export {};

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

@@ -0,0 +1,15 @@
+import { TimePickerSize } from './types';
+interface StyledWheelItemProps {
+    $size: TimePickerSize;
+    $isSelected: boolean;
+    $offset: number;
+}
+export declare const StyledWheelItem: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, StyledWheelItemProps>> & string;
+interface StyledRangeInputBoxProps {
+    $isFocused: boolean;
+    $isDisabled: boolean;
+    $error: boolean;
+}
+export declare const StyledRangeInputBox: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, StyledRangeInputBoxProps>> & string;
+export declare const StyledRangeInput: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, never>> & string;
+export {};

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

@@ -0,0 +1,3 @@
+import { InputHandle } from '../Input/types';
+import { TimePickerInputProps } from './types';
+export declare const TimePickerInput: import('react').ForwardRefExoticComponent<TimePickerInputProps & import('react').RefAttributes<InputHandle>>;

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

@@ -0,0 +1,2 @@
+import { TimePickerPopupProps } from './types';
+export declare const TimePickerPopup: ({ isOpen, anchorRef, onClose, children, size, isFixedPosition, }: TimePickerPopupProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+export interface TimePickerRangeInputProps {
+    startValue: string;
+    endValue: string;
+    onStartChange: (value: string) => void;
+    onEndChange: (value: string) => void;
+    onStartFocus: () => void;
+    onEndFocus: () => void;
+    onStartBlur?: () => void;
+    onEndBlur?: () => void;
+    onStartEnterPress?: () => void;
+    onEndEnterPress?: () => void;
+    onClear?: () => void;
+    hasValue?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+}
+export interface TimePickerRangeInputHandle {
+    focusStart: () => void;
+    focusEnd: () => void;
+    blurStart: () => void;
+    blurEnd: () => void;
+}
+export declare const TimePickerRangeInput: React.ForwardRefExoticComponent<TimePickerRangeInputProps & React.RefAttributes<TimePickerRangeInputHandle>>;

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

@@ -0,0 +1,2 @@
+import { TimePickerWheelProps } from './types';
+export declare const TimePickerWheel: ({ items, selectedValue, onSelect, size, }: TimePickerWheelProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+import { TimePickerWheelsProps } from './types';
+export declare const TimePickerWheels: ({ value, onChange, format, minuteStep, size, slots, markerValue, markerLabel, }: TimePickerWheelsProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { TimeFormat, TimePickerSize } from './types';
+export declare const DEFAULT_SIZE: TimePickerSize;
+export declare const DEFAULT_FORMAT: TimeFormat;
+export declare const DEFAULT_MINUTE_STEP = 1;
+export declare const DEFAULT_PLACEHOLDER = "Select time";
+export declare const DEFAULT_START_LABEL = "Start time";
+export declare const DEFAULT_END_LABEL = "End time";
+export declare const MASK_24H = "HH:mm";
+export declare const MASK_12H = "hh:mm AA";
+export declare const HOURS_24: string[];
+export declare const HOURS_12: string[];
+export declare const PERIODS: string[];

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

@@ -0,0 +1,25 @@
+import { TimeFormat, TimeValue } from './types';
+interface UseTimePickerStateProps {
+    value?: TimeValue | null;
+    onChange?: (value: TimeValue | null) => void;
+    format: TimeFormat;
+    minuteStep?: number;
+    slots?: TimeValue[];
+}
+interface UseTimePickerStateReturn {
+    isOpen: boolean;
+    setIsOpen: (open: boolean) => void;
+    inputValue: string;
+    setInputValue: (value: string) => void;
+    editingValue: TimeValue | null;
+    setEditingValue: (value: TimeValue | null) => void;
+    handleOpen: () => void;
+    handleClose: () => void;
+    handleClear: () => void;
+    handleInputChange: (inputText: string) => void;
+    handleWheelChange: (time: TimeValue) => void;
+    handleInputBlur: () => void;
+    handleEnterPress: () => void;
+}
+export declare function useTimePickerState({ value, onChange, format, minuteStep, slots, }: UseTimePickerStateProps): UseTimePickerStateReturn;
+export {};

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

@@ -0,0 +1,3 @@
+import { TimePickerProps, TimePickerHandle } from './types';
+export declare const TimePicker: import('react').ForwardRefExoticComponent<TimePickerProps & import('react').RefAttributes<TimePickerHandle>>;
+export type { TimePickerProps, TimePickerHandle, TimeValue } from './types';

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

@@ -0,0 +1,185 @@
+import { TimePickerSize, TimeFormat } from '../../theme/components/timepicker';
+import { BoxProps } from '../Box';
+export type { TimePickerSize, TimeFormat };
+/**
+ * Represents a time value with hours and minutes
+ */
+export interface TimeValue {
+    /** Hours (0-23 for 24h format, 1-12 for 12h format internally stored as 0-23) */
+    hours: number;
+    /** Minutes (0-59) */
+    minutes: number;
+}
+/**
+ * Props for the main TimePicker component
+ */
+export interface TimePickerProps extends Omit<BoxProps, 'onChange'> {
+    /**
+     * Current time value (single mode)
+     */
+    value?: TimeValue | null;
+    /**
+     * Callback when time changes (single mode)
+     */
+    onChange?: (value: TimeValue | null) => void;
+    /**
+     * Enable range mode (two time inputs: start and end)
+     * @default false
+     */
+    range?: boolean;
+    /**
+     * Start time value (range mode)
+     */
+    startValue?: TimeValue | null;
+    /**
+     * End time value (range mode)
+     */
+    endValue?: TimeValue | null;
+    /**
+     * Callback when start time changes (range mode)
+     */
+    onStartChange?: (value: TimeValue | null) => void;
+    /**
+     * Callback when end time changes (range mode)
+     */
+    onEndChange?: (value: TimeValue | null) => void;
+    /**
+     * Time display format
+     * @default '24h'
+     */
+    format?: TimeFormat;
+    /**
+     * Minute step for the wheel picker
+     * @default 1
+     */
+    minuteStep?: number;
+    /**
+     * Predefined time slots to choose from.
+     * When provided, shows a single wheel with these slots instead of hour/minute wheels.
+     * Example: [{ hours: 9, minutes: 0 }, { hours: 12, minutes: 30 }, { hours: 18, minutes: 0 }]
+     */
+    slots?: TimeValue[];
+    /**
+     * Size variant
+     * @default 'md'
+     */
+    size?: TimePickerSize;
+    /**
+     * Whether the picker is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Label text
+     */
+    label?: string;
+    /**
+     * Helper text below the input
+     */
+    helperText?: string;
+    /**
+     * Error message (takes precedence over helperText)
+     */
+    error?: string;
+    /**
+     * Use fixed positioning for popup (renders via portal to document.body).
+     * Useful when TimePicker is inside a container with overflow: hidden (e.g., Accordion).
+     * @default false
+     */
+    isFixedPosition?: boolean;
+}
+/**
+ * Props for TimePickerInput sub-component
+ */
+export interface TimePickerInputProps {
+    /** Current display value */
+    value: string;
+    /** Callback when input value changes */
+    onChange: (value: string) => void;
+    /** Callback when input is focused */
+    onFocus: () => void;
+    /** Callback when input loses focus */
+    onBlur?: () => void;
+    /** Callback when Enter key is pressed */
+    onEnterPress?: () => void;
+    /** Callback when clear button is clicked */
+    onClear?: () => void;
+    /** Label text */
+    label?: string;
+    /** Helper text */
+    helperText?: string;
+    /** Error message */
+    error?: string;
+    /** Whether input is disabled */
+    disabled?: boolean;
+    /** Whether the input has a value (show clear button) */
+    hasValue: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+}
+/**
+ * Props for TimePickerPopup sub-component
+ */
+export interface TimePickerPopupProps {
+    /** Whether popup is open */
+    isOpen: boolean;
+    /** Anchor element ref */
+    anchorRef: React.RefObject<HTMLDivElement | null>;
+    /** Close handler */
+    onClose: () => void;
+    /** Popup content */
+    children: React.ReactNode;
+    /** Size variant */
+    size: TimePickerSize;
+    /** Use fixed positioning for popup (portal to document.body) */
+    isFixedPosition?: boolean;
+}
+/**
+ * Props for TimePickerWheel sub-component
+ */
+export interface TimePickerWheelProps {
+    /** Array of values to display */
+    items: string[];
+    /** Currently selected value */
+    selectedValue: string;
+    /** Callback when value is selected */
+    onSelect: (value: string) => void;
+    /** Size variant */
+    size: TimePickerSize;
+}
+/**
+ * Props for TimePickerWheels container
+ */
+export interface TimePickerWheelsProps {
+    /** Current time value */
+    value: TimeValue | null;
+    /** Callback when time changes */
+    onChange: (value: TimeValue) => void;
+    /** Time format */
+    format: TimeFormat;
+    /** Minute step */
+    minuteStep: number;
+    /** Size variant */
+    size: TimePickerSize;
+    /** Predefined time slots (shows single wheel when provided) */
+    slots?: TimeValue[];
+    /** Marker value to show (the other time in range mode) */
+    markerValue?: TimeValue | null;
+    /** Label for marker (e.g., "Start:" or "End:") */
+    markerLabel?: string;
+}
+/**
+ * Handle for imperative API access
+ */
+export interface TimePickerHandle {
+    /** Open the picker popup */
+    open: () => void;
+    /** Close the picker popup */
+    close: () => void;
+    /** Reset to initial value */
+    reset: () => void;
+    /** Get current value */
+    getValue: () => TimeValue | null;
+    /** Focus the input */
+    focus: () => void;
+}

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

@@ -0,0 +1,73 @@
+import { TimeFormat, TimeValue } from './types';
+/**
+ * Generate minutes array based on step
+ */
+export declare function generateMinutes(step: number): string[];
+/**
+ * Convert 24h hours to 12h format
+ */
+export declare function to12Hour(hours24: number): {
+    hours: number;
+    period: 'AM' | 'PM';
+};
+/**
+ * Convert 12h format to 24h hours
+ */
+export declare function to24Hour(hours12: number, period: 'AM' | 'PM'): number;
+/**
+ * Format TimeValue to display string
+ */
+export declare function formatTime(value: TimeValue | null, format: TimeFormat): string;
+/**
+ * Parse display string to TimeValue
+ */
+export declare function parseTime(input: string, format: TimeFormat): TimeValue | null;
+/**
+ * Check if a string is a valid time input
+ */
+export declare function isValidTimeInput(input: string, format: TimeFormat): boolean;
+/**
+ * Get the mask pattern for input
+ */
+export declare function getMask(format: TimeFormat): string;
+/**
+ * Check if character at position is a mask placeholder
+ */
+export declare function isMaskPlaceholder(char: string): boolean;
+/**
+ * Apply typed digits to mask
+ */
+export declare function applyInputToMask(digits: string, mask: string): string;
+/**
+ * Snap minutes to nearest step
+ */
+export declare function snapToStep(minutes: number, step: number): number;
+/**
+ * Create TimeValue with snapped minutes
+ */
+export declare function createTimeValue(hours: number, minutes: number, minuteStep: number): TimeValue;
+/**
+ * Format a slot (TimeValue) to display string for wheel
+ */
+export declare function formatSlot(slot: TimeValue, format: TimeFormat): string;
+/**
+ * Check if two TimeValue are equal
+ */
+export declare function isTimeEqual(a: TimeValue | null, b: TimeValue | null): boolean;
+/**
+ * Convert TimeValue to minutes from midnight for comparison
+ */
+export declare function timeValueToMinutes(time: TimeValue): number;
+/**
+ * Compare two TimeValues
+ * Returns:
+ *   -1 if a < b
+ *    0 if a === b
+ *    1 if a > b
+ *   null if either value is null/undefined (incomparable)
+ */
+export declare function compareTimeValues(a: TimeValue | null | undefined, b: TimeValue | null | undefined): -1 | 0 | 1 | null;
+/**
+ * Find index of slot in slots array
+ */
+export declare function findSlotIndex(slots: TimeValue[], value: TimeValue | null): number;

package/dist/components/index.d.ts

@@ -25,3 +25,5 @@ export * from './Tooltip';
 export * from './BarChart';
 export * from './PieChart';
 export * from './LineChart';
+export * from './DatePicker';
+export * from './TimePicker';

package/dist/hooks/index.d.ts

@@ -7,3 +7,4 @@ export * from './useInteractionDetector';
 export * from './useEventListener';
 export * from './useIsomorphicLayoutEffect';
 export * from './useUserAgent';
+export * from './usePopupPosition';

package/dist/hooks/usePopupPosition.d.ts

@@ -0,0 +1,15 @@
+interface UsePopupPositionProps<TAnchor extends HTMLElement = HTMLElement, TPopup extends HTMLElement = HTMLElement> {
+    anchorRef: React.RefObject<TAnchor | null>;
+    popupRef: React.RefObject<TPopup | null>;
+    offsetValue: number;
+    isOpen: boolean;
+    /** Use fixed positioning relative to viewport (for portal popups) */
+    useFixedPosition?: boolean;
+}
+/**
+ * Hook to calculate and update popup position relative to anchor element
+ * Position is calculated relative to container (using position: absolute)
+ * Automatically handles initial positioning and resize events
+ */
+export declare function usePopupPosition<TAnchor extends HTMLElement = HTMLElement, TPopup extends HTMLElement = HTMLElement>({ anchorRef, popupRef, offsetValue, isOpen, useFixedPosition, }: UsePopupPositionProps<TAnchor, TPopup>): void;
+export {};