@izonnet-web-solution/react-native-date-time-picker-kit 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +139 -19
  2. package/lib/module/components/CalendarPicker.js +12 -7
  3. package/lib/module/components/CalendarPicker.js.map +1 -1
  4. package/lib/module/components/DatePicker.js +21 -14
  5. package/lib/module/components/DatePicker.js.map +1 -1
  6. package/lib/module/components/DateRangePicker.js +10 -6
  7. package/lib/module/components/DateRangePicker.js.map +1 -1
  8. package/lib/module/components/DateTimePicker.js +115 -39
  9. package/lib/module/components/DateTimePicker.js.map +1 -1
  10. package/lib/module/components/TimePicker.js +7 -5
  11. package/lib/module/components/TimePicker.js.map +1 -1
  12. package/lib/module/components/WheelPicker.js +62 -41
  13. package/lib/module/components/WheelPicker.js.map +1 -1
  14. package/lib/module/components/common/ModalWrapper.js +8 -2
  15. package/lib/module/components/common/ModalWrapper.js.map +1 -1
  16. package/lib/module/localization/useLocale.js +54 -4
  17. package/lib/module/localization/useLocale.js.map +1 -1
  18. package/lib/module/theme/useTheme.js +23 -1
  19. package/lib/module/theme/useTheme.js.map +1 -1
  20. package/lib/module/utils/dateConversion.js +109 -0
  21. package/lib/module/utils/dateConversion.js.map +1 -1
  22. package/lib/typescript/src/components/CalendarPicker.d.ts +16 -0
  23. package/lib/typescript/src/components/CalendarPicker.d.ts.map +1 -1
  24. package/lib/typescript/src/components/DatePicker.d.ts +13 -1
  25. package/lib/typescript/src/components/DatePicker.d.ts.map +1 -1
  26. package/lib/typescript/src/components/DateRangePicker.d.ts +16 -1
  27. package/lib/typescript/src/components/DateRangePicker.d.ts.map +1 -1
  28. package/lib/typescript/src/components/DateTimePicker.d.ts.map +1 -1
  29. package/lib/typescript/src/components/TimePicker.d.ts +7 -1
  30. package/lib/typescript/src/components/TimePicker.d.ts.map +1 -1
  31. package/lib/typescript/src/components/WheelPicker.d.ts.map +1 -1
  32. package/lib/typescript/src/components/common/ModalWrapper.d.ts +1 -0
  33. package/lib/typescript/src/components/common/ModalWrapper.d.ts.map +1 -1
  34. package/lib/typescript/src/localization/useLocale.d.ts +1 -1
  35. package/lib/typescript/src/localization/useLocale.d.ts.map +1 -1
  36. package/lib/typescript/src/theme/types.d.ts +11 -0
  37. package/lib/typescript/src/theme/types.d.ts.map +1 -1
  38. package/lib/typescript/src/theme/useTheme.d.ts.map +1 -1
  39. package/lib/typescript/src/types/presentation.d.ts +7 -0
  40. package/lib/typescript/src/types/presentation.d.ts.map +1 -1
  41. package/lib/typescript/src/types/props.d.ts +154 -1
  42. package/lib/typescript/src/types/props.d.ts.map +1 -1
  43. package/lib/typescript/src/utils/dateConversion.d.ts +19 -0
  44. package/lib/typescript/src/utils/dateConversion.d.ts.map +1 -1
  45. package/package.json +16 -8
  46. package/src/components/CalendarPicker.tsx +38 -8
  47. package/src/components/DatePicker.tsx +45 -15
  48. package/src/components/DateRangePicker.tsx +31 -6
  49. package/src/components/DateTimePicker.tsx +217 -51
  50. package/src/components/TimePicker.tsx +18 -5
  51. package/src/components/WheelPicker.tsx +86 -56
  52. package/src/components/common/ModalWrapper.tsx +9 -1
  53. package/src/localization/useLocale.ts +64 -4
  54. package/src/theme/types.ts +12 -0
  55. package/src/theme/useTheme.ts +24 -1
  56. package/src/types/presentation.ts +7 -0
  57. package/src/types/props.ts +198 -11
  58. package/src/utils/dateConversion.ts +146 -0
@@ -1,8 +1,10 @@
1
1
  import React, { useCallback, useEffect, useRef } from 'react';
2
2
  import {
3
+ FlatList,
4
+ type ListRenderItemInfo,
3
5
  type NativeScrollEvent,
4
6
  type NativeSyntheticEvent,
5
- ScrollView,
7
+ Platform,
6
8
  StyleSheet,
7
9
  Text,
8
10
  TouchableOpacity,
@@ -36,7 +38,7 @@ export function WheelPicker<T = any>({
36
38
  testID,
37
39
  }: WheelPickerProps<T>): React.ReactElement {
38
40
  const theme = useTheme(propTheme);
39
- const scrollRef = useRef<any>(null);
41
+ const flatListRef = useRef<FlatList<WheelPickerItem<T>>>(null);
40
42
  const isScrollingRef = useRef(false);
41
43
 
42
44
  const halfVisible = Math.floor(visibleItems / 2);
@@ -47,11 +49,15 @@ export function WheelPicker<T = any>({
47
49
 
48
50
  // Scroll to position when selectedValue changes externally
49
51
  useEffect(() => {
50
- if (!isScrollingRef.current && scrollRef.current && activeIndex >= 0) {
51
- scrollRef.current.scrollTo({
52
- y: activeIndex * itemHeight,
53
- animated: false,
54
- });
52
+ if (!isScrollingRef.current && flatListRef.current && activeIndex >= 0) {
53
+ try {
54
+ flatListRef.current.scrollToOffset({
55
+ offset: activeIndex * itemHeight,
56
+ animated: false,
57
+ });
58
+ } catch {
59
+ // Fallback for initial render
60
+ }
55
61
  }
56
62
  }, [activeIndex, itemHeight]);
57
63
 
@@ -75,8 +81,8 @@ export function WheelPicker<T = any>({
75
81
 
76
82
  const handleItemPress = useCallback(
77
83
  (index: number) => {
78
- scrollRef.current?.scrollTo({
79
- y: index * itemHeight,
84
+ flatListRef.current?.scrollToOffset({
85
+ offset: index * itemHeight,
80
86
  animated: true,
81
87
  });
82
88
  const item = items[index];
@@ -87,6 +93,63 @@ export function WheelPicker<T = any>({
87
93
  [itemHeight, items, onChange]
88
94
  );
89
95
 
96
+ const renderItem = useCallback(
97
+ ({ item, index }: ListRenderItemInfo<WheelPickerItem<T>>) => {
98
+ const isSelected = index === activeIndex;
99
+ return (
100
+ <TouchableOpacity
101
+ key={`wheel-${index}-${String(item.value)}`}
102
+ accessibilityRole="button"
103
+ accessibilityLabel={item.label}
104
+ accessibilityState={{ selected: isSelected }}
105
+ activeOpacity={0.8}
106
+ onPress={() => handleItemPress(index)}
107
+ style={[
108
+ styles.itemRow,
109
+ {
110
+ height: itemHeight,
111
+ },
112
+ ]}
113
+ >
114
+ <Text
115
+ numberOfLines={1}
116
+ style={[
117
+ styles.itemText,
118
+ {
119
+ color: isSelected ? theme.colors.text : theme.colors.textMuted,
120
+ fontSize: isSelected
121
+ ? theme.typography.fontSizeLarge
122
+ : theme.typography.fontSizeMedium,
123
+ fontWeight: isSelected
124
+ ? theme.typography.fontWeightBold
125
+ : theme.typography.fontWeightRegular,
126
+ transform: isSelected ? [{ scale: 1.05 }] : [{ scale: 0.95 }],
127
+ },
128
+ ]}
129
+ >
130
+ {item.label}
131
+ </Text>
132
+ </TouchableOpacity>
133
+ );
134
+ },
135
+ [activeIndex, handleItemPress, itemHeight, theme]
136
+ );
137
+
138
+ const getItemLayout = useCallback(
139
+ (_: any, index: number) => ({
140
+ length: itemHeight,
141
+ offset: itemHeight * index,
142
+ index,
143
+ }),
144
+ [itemHeight]
145
+ );
146
+
147
+ const keyExtractor = useCallback(
148
+ (item: WheelPickerItem<T>, index: number) =>
149
+ `wheel-${index}-${String(item.value)}`,
150
+ []
151
+ );
152
+
90
153
  return (
91
154
  <View
92
155
  testID={testID}
@@ -112,63 +175,30 @@ export function WheelPicker<T = any>({
112
175
  ]}
113
176
  />
114
177
 
115
- {/* Wheel ScrollView */}
116
- <ScrollView
117
- ref={scrollRef}
178
+ {/* Optimized FlatList Wheel */}
179
+ <FlatList
180
+ ref={flatListRef}
181
+ data={items}
182
+ renderItem={renderItem}
183
+ keyExtractor={keyExtractor}
184
+ getItemLayout={getItemLayout}
185
+ initialScrollIndex={
186
+ activeIndex >= 0 && activeIndex < items.length ? activeIndex : 0
187
+ }
118
188
  showsVerticalScrollIndicator={false}
119
189
  snapToInterval={itemHeight}
120
190
  snapToAlignment="center"
121
191
  decelerationRate="fast"
192
+ removeClippedSubviews={Platform.OS === 'android'}
193
+ maxToRenderPerBatch={visibleItems * 2}
194
+ windowSize={visibleItems + 2}
122
195
  onScrollBeginDrag={handleScrollBeginDrag}
123
196
  onMomentumScrollEnd={handleMomentumScrollEnd}
124
197
  contentContainerStyle={{
125
198
  paddingTop: halfVisible * itemHeight,
126
199
  paddingBottom: halfVisible * itemHeight,
127
200
  }}
128
- >
129
- {items.map((item, index) => {
130
- const isSelected = index === activeIndex;
131
- return (
132
- <TouchableOpacity
133
- key={`wheel-${index}-${String(item.value)}`}
134
- accessibilityRole="button"
135
- accessibilityLabel={item.label}
136
- accessibilityState={{ selected: isSelected }}
137
- activeOpacity={0.8}
138
- onPress={() => handleItemPress(index)}
139
- style={[
140
- styles.itemRow,
141
- {
142
- height: itemHeight,
143
- },
144
- ]}
145
- >
146
- <Text
147
- numberOfLines={1}
148
- style={[
149
- styles.itemText,
150
- {
151
- color: isSelected
152
- ? theme.colors.text
153
- : theme.colors.textMuted,
154
- fontSize: isSelected
155
- ? theme.typography.fontSizeLarge
156
- : theme.typography.fontSizeMedium,
157
- fontWeight: isSelected
158
- ? theme.typography.fontWeightBold
159
- : theme.typography.fontWeightRegular,
160
- transform: isSelected
161
- ? [{ scale: 1.05 }]
162
- : [{ scale: 0.95 }],
163
- },
164
- ]}
165
- >
166
- {item.label}
167
- </Text>
168
- </TouchableOpacity>
169
- );
170
- })}
171
- </ScrollView>
201
+ />
172
202
  </View>
173
203
  );
174
204
  }
@@ -18,11 +18,13 @@ export interface ModalWrapperProps extends BaseModalProps {
18
18
  presentation?: PresentationMode;
19
19
  children: React.ReactNode;
20
20
  theme: ResolvedTheme;
21
+ isVisible?: boolean;
21
22
  }
22
23
 
23
24
  export const ModalWrapper: React.FC<ModalWrapperProps> = ({
24
25
  presentation = 'modal',
25
26
  visible = false,
27
+ isVisible,
26
28
  onClose,
27
29
  children,
28
30
  theme,
@@ -31,6 +33,7 @@ export const ModalWrapper: React.FC<ModalWrapperProps> = ({
31
33
  showHandle = true,
32
34
  closeOnBackdropPress = true,
33
35
  }) => {
36
+ const modalVisible = isVisible !== undefined ? isVisible : visible;
34
37
  if (presentation === 'inline') {
35
38
  return (
36
39
  <View
@@ -67,7 +70,7 @@ export const ModalWrapper: React.FC<ModalWrapperProps> = ({
67
70
  return (
68
71
  <Modal
69
72
  transparent={!isFullscreen}
70
- visible={visible}
73
+ visible={modalVisible}
71
74
  animationType={effectiveAnim}
72
75
  onRequestClose={onClose}
73
76
  statusBarTranslucent
@@ -123,6 +126,11 @@ export const ModalWrapper: React.FC<ModalWrapperProps> = ({
123
126
  </View>
124
127
  )}
125
128
  {children}
129
+ {isBottomSheet && (
130
+ <SafeAreaView
131
+ style={{ backgroundColor: theme.colors.modalBackground }}
132
+ />
133
+ )}
126
134
  </View>
127
135
  </View>
128
136
  )}
@@ -16,26 +16,79 @@ export function getDeviceLocale(): string {
16
16
  return 'en';
17
17
  }
18
18
 
19
+ function getIntlLocaleData(localeCode: string): LocaleData {
20
+ const base = enLocale;
21
+ try {
22
+ if (typeof Intl !== 'undefined' && Intl.DateTimeFormat) {
23
+ const months: string[] = [];
24
+ const monthsShort: string[] = [];
25
+ for (let m = 0; m < 12; m++) {
26
+ const d = new Date(2026, m, 1);
27
+ months.push(
28
+ new Intl.DateTimeFormat(localeCode, { month: 'long' }).format(d)
29
+ );
30
+ monthsShort.push(
31
+ new Intl.DateTimeFormat(localeCode, { month: 'short' }).format(d)
32
+ );
33
+ }
34
+
35
+ const weekdays: string[] = [];
36
+ const weekdaysShort: string[] = [];
37
+ const weekdaysMin: string[] = [];
38
+ // 2026-11-15 was Sunday
39
+ for (let w = 0; w < 7; w++) {
40
+ const d = new Date(2026, 10, 15 + w);
41
+ weekdays.push(
42
+ new Intl.DateTimeFormat(localeCode, { weekday: 'long' }).format(d)
43
+ );
44
+ weekdaysShort.push(
45
+ new Intl.DateTimeFormat(localeCode, { weekday: 'short' }).format(d)
46
+ );
47
+ weekdaysMin.push(
48
+ new Intl.DateTimeFormat(localeCode, { weekday: 'narrow' }).format(d)
49
+ );
50
+ }
51
+
52
+ return {
53
+ ...base,
54
+ code: localeCode,
55
+ months,
56
+ monthsShort,
57
+ weekdays,
58
+ weekdaysShort,
59
+ weekdaysMin,
60
+ };
61
+ }
62
+ } catch {
63
+ // fallback to base English
64
+ }
65
+ return { ...base, code: localeCode };
66
+ }
67
+
19
68
  export function resolveLocale(
20
69
  localeInput?: string | PartialLocaleData | null
21
70
  ): LocaleData {
22
71
  if (!localeInput) {
23
72
  const devLocale = getDeviceLocale();
24
73
  const langCode = devLocale.split('-')[0]?.toLowerCase() || 'en';
25
- const base = BUILTIN_LOCALES[langCode] || enLocale;
74
+ const base = BUILTIN_LOCALES[langCode] || getIntlLocaleData(devLocale);
26
75
  return { ...base, code: devLocale };
27
76
  }
28
77
 
29
78
  if (typeof localeInput === 'string') {
30
79
  const langCode = localeInput.split('-')[0]?.toLowerCase() || 'en';
31
80
  const base =
32
- BUILTIN_LOCALES[langCode] || BUILTIN_LOCALES[localeInput] || enLocale;
81
+ BUILTIN_LOCALES[langCode] ||
82
+ BUILTIN_LOCALES[localeInput] ||
83
+ getIntlLocaleData(localeInput);
33
84
  return { ...base, code: localeInput };
34
85
  }
35
86
 
36
87
  // It's a custom PartialLocaleData object
37
88
  const langCode = localeInput.code?.split('-')[0]?.toLowerCase() || 'en';
38
- const base = BUILTIN_LOCALES[langCode] || enLocale;
89
+ const base =
90
+ BUILTIN_LOCALES[langCode] ||
91
+ (localeInput.code ? getIntlLocaleData(localeInput.code) : enLocale);
39
92
 
40
93
  return {
41
94
  ...base,
@@ -83,12 +136,19 @@ export function useLocale(
83
136
  export function formatLocalized(
84
137
  date: Date,
85
138
  formatStr: string = 'YYYY-MM-DD',
86
- locale: LocaleData = enLocale
139
+ localeInput: string | PartialLocaleData | LocaleData = enLocale
87
140
  ): string {
88
141
  if (isNaN(date.getTime())) {
89
142
  return '';
90
143
  }
91
144
 
145
+ const locale: LocaleData =
146
+ typeof localeInput === 'string' ||
147
+ !('months' in localeInput) ||
148
+ !Array.isArray((localeInput as any).months)
149
+ ? resolveLocale(localeInput as string | PartialLocaleData)
150
+ : (localeInput as LocaleData);
151
+
92
152
  const year = date.getFullYear();
93
153
  const month = date.getMonth(); // 0-11
94
154
  const day = date.getDate();
@@ -53,9 +53,21 @@ export interface ThemeBorderRadius {
53
53
  full: number;
54
54
  }
55
55
 
56
+ export interface ThemeColorsOverride {
57
+ backgroundColor?: string;
58
+ textColor?: string;
59
+ selectedTextColor?: string;
60
+ accentColor?: string;
61
+ dividerColor?: string;
62
+ headerBackground?: string;
63
+ cardBackground?: string;
64
+ borderColor?: string;
65
+ }
66
+
56
67
  export interface ThemeConfig {
57
68
  mode?: ThemeMode;
58
69
  colors?: Partial<ThemeColors>;
70
+ themeColors?: ThemeColorsOverride;
59
71
  typography?: Partial<ThemeTypography>;
60
72
  spacing?: Partial<ThemeSpacing>;
61
73
  borderRadius?: Partial<ThemeBorderRadius>;
@@ -43,11 +43,34 @@ export function resolveTheme(
43
43
  return baseTheme;
44
44
  }
45
45
 
46
+ const mappedColors = {
47
+ ...config?.colors,
48
+ ...(config?.themeColors?.backgroundColor && {
49
+ background: config.themeColors.backgroundColor,
50
+ modalBackground: config.themeColors.backgroundColor,
51
+ }),
52
+ ...(config?.themeColors?.textColor && {
53
+ text: config.themeColors.textColor,
54
+ }),
55
+ ...(config?.themeColors?.selectedTextColor && {
56
+ selectedText: config.themeColors.selectedTextColor,
57
+ }),
58
+ ...(config?.themeColors?.accentColor && {
59
+ accent: config.themeColors.accentColor,
60
+ primary: config.themeColors.accentColor,
61
+ selected: config.themeColors.accentColor,
62
+ }),
63
+ ...(config?.themeColors?.dividerColor && {
64
+ divider: config.themeColors.dividerColor,
65
+ border: config.themeColors.dividerColor,
66
+ }),
67
+ };
68
+
46
69
  return {
47
70
  mode,
48
71
  colors: {
49
72
  ...baseTheme.colors,
50
- ...config.colors,
73
+ ...mappedColors,
51
74
  },
52
75
  typography: {
53
76
  ...defaultTypography,
@@ -4,7 +4,14 @@ export type PresentationMode =
4
4
  export type ModalAnimationType = 'slide' | 'fade' | 'none';
5
5
 
6
6
  export interface BaseModalProps {
7
+ /**
8
+ * Visibility flag for modal presentation.
9
+ */
7
10
  visible?: boolean;
11
+ /**
12
+ * Alias for `visible`.
13
+ */
14
+ isVisible?: boolean;
8
15
  onClose?: () => void;
9
16
  title?: string;
10
17
  confirmText?: string;
@@ -12,7 +12,11 @@ import type {
12
12
  DateTimePickerErrorEvent,
13
13
  DateTimePickerOpenEvent,
14
14
  } from './events';
15
- import type { ThemeConfig, ThemeMode } from '../theme/types';
15
+ import type {
16
+ ThemeColorsOverride,
17
+ ThemeConfig,
18
+ ThemeMode,
19
+ } from '../theme/types';
16
20
  import type { PartialLocaleData } from '../localization/types';
17
21
  import type { BaseModalProps, PresentationMode } from './presentation';
18
22
  import type { MarkedDatesMap } from '../components/CalendarPicker';
@@ -20,6 +24,11 @@ import type { DatePreset } from '../presets';
20
24
 
21
25
  export type MinuteInterval = 1 | 2 | 3 | 4 | 5 | 6 | 10 | 12 | 15 | 20 | 30;
22
26
 
27
+ export type PickerMode = NativePickerMode;
28
+ export type PickerTheme = NativePickerTheme | ThemeMode;
29
+ export type PickerDisplay = NativePickerDisplay;
30
+ export type PickerPresentation = PresentationMode;
31
+
23
32
  export interface TimeObject {
24
33
  hour: number;
25
34
  minute: number;
@@ -30,55 +39,233 @@ export interface DateTimePickerProps extends Omit<
30
39
  BaseModalProps,
31
40
  'onConfirm' | 'onCancel'
32
41
  > {
33
- // Selection
42
+ /**
43
+ * Selection mode for picker: 'date', 'time', 'datetime', or 'countdown'.
44
+ * @default 'date'
45
+ */
34
46
  mode?: NativePickerMode;
47
+
48
+ /**
49
+ * Controlled Date value. Accepts Date object, numeric epoch timestamp, or ISO string.
50
+ */
35
51
  value?: Date | number | string | null;
52
+
53
+ /**
54
+ * Uncontrolled initial Date value.
55
+ */
36
56
  defaultValue?: Date | number | string | null;
57
+
58
+ /**
59
+ * Native display presentation style on iOS/Android (e.g. 'compact', 'inline', 'spinner', 'clock').
60
+ * @default 'default'
61
+ */
37
62
  display?: NativePickerDisplay;
63
+
64
+ /**
65
+ * Whether the picker interactions are disabled.
66
+ * @default false
67
+ */
38
68
  disabled?: boolean;
39
- presentation?: PresentationMode; // 'native' | 'inline' | 'modal' | 'bottom-sheet' | 'fullscreen'
40
69
 
41
- // Restrictions
70
+ /**
71
+ * Presentation mode: 'native' (OS dialog), 'inline', 'modal', 'bottom-sheet', or 'fullscreen'.
72
+ * @default 'native'
73
+ */
74
+ presentation?: PresentationMode;
75
+
76
+ /**
77
+ * Minimum selectable date/time boundary. Selection before this timestamp is prevented/clamped.
78
+ */
42
79
  minimumDate?: Date | number | string;
80
+
81
+ /**
82
+ * Alias for `minimumDate`.
83
+ */
84
+ minDate?: Date | number | string;
85
+
86
+ /**
87
+ * Maximum selectable date/time boundary. Selection after this timestamp is prevented/clamped.
88
+ */
43
89
  maximumDate?: Date | number | string;
90
+
91
+ /**
92
+ * Alias for `maximumDate`.
93
+ */
94
+ maxDate?: Date | number | string;
95
+
96
+ /**
97
+ * Minimum allowable time components (e.g. "09:00" or { hour: 9, minute: 0 }).
98
+ */
44
99
  minimumTime?: string | TimeObject;
100
+
101
+ /**
102
+ * Maximum allowable time components (e.g. "17:00" or { hour: 17, minute: 0 }).
103
+ */
45
104
  maximumTime?: string | TimeObject;
105
+
106
+ /**
107
+ * Minute snapping interval (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, or 30).
108
+ * @default 1
109
+ */
46
110
  minuteInterval?: MinuteInterval;
111
+
112
+ /**
113
+ * Specific dates to disable from selection.
114
+ */
47
115
  disabledDates?: (Date | string)[];
48
- disabledWeekdays?: number[]; // 0 = Sunday, 1 = Monday, ..., 6 = Saturday
116
+
117
+ /**
118
+ * Weekdays to disable from selection (0 = Sunday, 1 = Monday, ..., 6 = Saturday).
119
+ */
120
+ disabledWeekdays?: number[];
121
+
122
+ /**
123
+ * Map of marked dates with colored dots, badges, or custom highlights.
124
+ */
49
125
  markedDates?: MarkedDatesMap;
50
126
 
51
- // Localization
127
+ /**
128
+ * Locale string identifier (e.g. 'en', 'hi', 'gu', 'ar', 'es') or custom LocaleData object.
129
+ * @default Device locale
130
+ */
52
131
  locale?: string | PartialLocaleData;
132
+
133
+ /**
134
+ * Target IANA timezone identifier (e.g. 'America/New_York', 'Asia/Kolkata').
135
+ */
136
+ timeZone?: string;
137
+
138
+ /**
139
+ * Alias for `timeZone`.
140
+ */
53
141
  timeZoneName?: string;
142
+
143
+ /**
144
+ * Explicit UTC offset in minutes (e.g. 330 for IST +05:30).
145
+ */
54
146
  timeZoneOffsetInMinutes?: number;
147
+
148
+ /**
149
+ * UTC offset in hours or minutes (e.g. 5.5 or 330).
150
+ */
151
+ utcOffset?: number;
152
+
153
+ /**
154
+ * Explicit override for 24-hour time representation.
155
+ */
55
156
  is24Hour?: boolean;
56
- firstDayOfWeek?: number; // 0 = Sunday, 1 = Monday, ..., 6 = Saturday
57
157
 
58
- // Appearance
158
+ /**
159
+ * First day of the week (0 = Sunday, 1 = Monday, 6 = Saturday).
160
+ */
161
+ firstDayOfWeek?: number;
162
+
163
+ /**
164
+ * Visual theme mode ('light', 'dark', 'auto') or comprehensive ThemeConfig object.
165
+ * @default 'auto'
166
+ */
59
167
  theme?: NativePickerTheme | ThemeMode | ThemeConfig;
168
+
169
+ /**
170
+ * Convenient color override palette for quick styling without breaking layouts.
171
+ */
172
+ themeColors?: ThemeColorsOverride;
173
+
174
+ /**
175
+ * Optional custom style overrides for modal header, button, or container.
176
+ */
177
+ styles?: {
178
+ headerStyle?: any;
179
+ confirmButtonStyle?: any;
180
+ cancelButtonStyle?: any;
181
+ containerStyle?: any;
182
+ };
183
+
184
+ /**
185
+ * Title text displayed in header or native dialog.
186
+ */
60
187
  title?: string;
188
+
189
+ /**
190
+ * Confirm button action label.
191
+ */
61
192
  confirmText?: string;
193
+
194
+ /**
195
+ * Cancel button action label.
196
+ */
62
197
  cancelText?: string;
198
+
199
+ /**
200
+ * Accent color override.
201
+ */
63
202
  accentColor?: string;
203
+
204
+ /**
205
+ * Text color override.
206
+ */
64
207
  textColor?: string;
208
+
209
+ /**
210
+ * Background color override.
211
+ */
65
212
  backgroundColor?: string;
213
+
214
+ /**
215
+ * Whether to show quick date presets bar (Today, Yesterday, Last 7 Days, This Month).
216
+ * @default false
217
+ */
66
218
  showPresets?: boolean;
219
+
220
+ /**
221
+ * Custom date presets to display.
222
+ */
67
223
  customPresets?: DatePreset[];
68
224
 
69
- // Callbacks
225
+ /**
226
+ * Callback fired on any intermediate date or time selection change.
227
+ */
70
228
  onChange?: DateTimePickerChangeEvent;
229
+
230
+ /**
231
+ * Callback fired when selection is confirmed with the final Date object.
232
+ */
71
233
  onConfirm?: DateTimePickerConfirmEvent;
234
+
235
+ /**
236
+ * Callback fired when picker is cancelled or closed without confirmation.
237
+ */
72
238
  onCancel?: DateTimePickerCancelEvent;
239
+
240
+ /**
241
+ * Callback fired on native dialog dismissal.
242
+ */
73
243
  onDismiss?: DateTimePickerDismissEvent;
244
+
245
+ /**
246
+ * Callback fired when picker modal opens.
247
+ */
74
248
  onOpen?: DateTimePickerOpenEvent;
249
+
250
+ /**
251
+ * Callback fired when an error occurs during presentation or validation.
252
+ */
75
253
  onError?: DateTimePickerErrorEvent;
76
254
 
77
- // Testing
255
+ /**
256
+ * Test identifier for automation testing.
257
+ */
78
258
  testID?: string;
79
259
 
80
- // Declarative open control (optional)
260
+ /**
261
+ * Declarative open control flag.
262
+ */
81
263
  open?: boolean;
264
+
265
+ /**
266
+ * Alias for `open` or `visible`.
267
+ */
268
+ isVisible?: boolean;
82
269
  }
83
270
 
84
271
  export interface DateTimePickerRef {