@dayflow/core 3.1.2 → 3.2.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.
package/dist/index.d.ts CHANGED
@@ -1,27 +1,10 @@
1
- import { Temporal } from 'temporal-polyfill';
2
1
  import * as preact from 'preact';
3
- import { ComponentChildren, RefObject, h } from 'preact';
2
+ import { ComponentChildren, AnyComponent, h, RefObject, JSX } from 'preact';
3
+ import { Temporal } from 'temporal-polyfill';
4
4
  import * as preact_compat from 'preact/compat';
5
5
  export { createPortal } from 'preact/compat';
6
6
  import { BlossomColorPickerOptions } from '@dayflow/blossom-color-picker';
7
7
 
8
- /**
9
- * Calendar event interface (using Temporal API)
10
- * Unified event data structure supporting single-day, cross-day, and all-day events
11
- */
12
- interface Event {
13
- id: string;
14
- title: string;
15
- description?: string;
16
- start: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime;
17
- end: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime;
18
- allDay?: boolean;
19
- icon?: boolean | ComponentChildren;
20
- calendarId?: string;
21
- meta?: Record<string, any>;
22
- day?: number;
23
- }
24
-
25
8
  type ViewSwitcherMode = 'buttons' | 'select';
26
9
 
27
10
  /**
@@ -183,11 +166,11 @@ declare class CalendarRegistry {
183
166
  /**
184
167
  * Check if the current theme is dark
185
168
  */
186
- private isDarkTheme;
169
+ private static isDarkTheme;
187
170
  /**
188
171
  * Validate calendar configuration
189
172
  */
190
- validate(calendar: Partial<CalendarType>): string[];
173
+ static validate(calendar: Partial<CalendarType>): string[];
191
174
  }
192
175
  /**
193
176
  * Get calendar colors for a specific hex color
@@ -208,31 +191,143 @@ interface Locale {
208
191
  }
209
192
 
210
193
  /**
211
- * Mobile event drawer/dialog Props
194
+ * Calendar event interface (using Temporal API)
195
+ * Unified event data structure supporting single-day, cross-day, and all-day events
212
196
  */
213
- interface MobileEventProps {
214
- /** Whether the drawer/dialog is open */
215
- isOpen: boolean;
216
- /** Callback to close the drawer/dialog */
217
- onClose: () => void;
218
- /** Callback to save the event (creates or updates) */
219
- onSave: (event: Event) => void;
220
- /** Callback to delete an existing event by id */
221
- onEventDelete?: (id: string) => void;
222
- /** Current event data (newly created template or existing event) */
223
- draftEvent: Event | null;
224
- /** The ICalendarApp instance providing built-in services */
225
- app: ICalendarApp;
197
+ interface Event {
198
+ id: string;
199
+ title: string;
200
+ description?: string;
201
+ start: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime;
202
+ end: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime;
203
+ allDay?: boolean;
204
+ icon?: boolean | ComponentChildren;
205
+ calendarId?: string;
206
+ meta?: Record<string, unknown>;
207
+ day?: number;
226
208
  }
209
+
227
210
  /**
228
- * Custom mobile event renderer (Drawer or Dialog)
211
+ * Event layout configuration constants
212
+ * Controls visual presentation of events in the calendar
213
+ */
214
+ declare const LAYOUT_CONFIG: {
215
+ readonly INDENT_STEP: 2;
216
+ readonly MIN_WIDTH: 25;
217
+ readonly MARGIN_BETWEEN: 2;
218
+ readonly CONTAINER_WIDTH: 320;
219
+ readonly OVERLAP_THRESHOLD: 0.25;
220
+ readonly EDGE_MARGIN: 3;
221
+ readonly MAX_LOAD_IMBALANCE: 0;
222
+ readonly REBALANCE_THRESHOLD: 2;
223
+ };
224
+ /**
225
+ * Event layout interface
226
+ * Defines position and styling of events in the UI
227
+ */
228
+ interface EventLayout {
229
+ id: string;
230
+ left: number;
231
+ width: number;
232
+ zIndex: number;
233
+ level: number;
234
+ isPrimary: boolean;
235
+ indentOffset: number;
236
+ importance: number;
237
+ }
238
+ /**
239
+ * Nested layer interface
240
+ * Represents hierarchical relationships of events
241
+ */
242
+ interface NestedLayer {
243
+ events: Event[];
244
+ level: number;
245
+ parentEvent?: Event;
246
+ timeSlot?: {
247
+ start: number;
248
+ end: number;
249
+ };
250
+ }
251
+ /**
252
+ * Event group interface
253
+ * Represents a group of related events and their nested structure
254
+ */
255
+ interface EventGroup {
256
+ events: Event[];
257
+ startHour: number;
258
+ endHour: number;
259
+ primaryEvent?: Event;
260
+ nestedStructure: NestedLayer[];
261
+ specialLayoutRules?: SpecialLayoutRule[];
262
+ originalBranchMap?: Map<string, Event>;
263
+ }
264
+ /**
265
+ * Event relationship information interface
266
+ * Describes relationships of events in nested structures
267
+ */
268
+ interface EventRelations {
269
+ directChildren: Event[];
270
+ allDescendants: Event[];
271
+ directParent: Event | null;
272
+ layer: NestedLayer | null;
273
+ subtreeSize: number;
274
+ isLeaf: boolean;
275
+ }
276
+ /**
277
+ * Subtree analysis interface
278
+ * Used to analyze structural information of event trees
279
+ */
280
+ interface SubtreeAnalysis {
281
+ rootEvent: Event;
282
+ allDescendants: Event[];
283
+ timeSpan: {
284
+ start: number;
285
+ end: number;
286
+ duration: number;
287
+ };
288
+ descendantCount: number;
289
+ maxDepth: number;
290
+ branchPath: Event[];
291
+ }
292
+ /**
293
+ * Balance strategy interface
294
+ * Used for balance algorithms to optimize event layouts
229
295
  */
230
- type MobileEventRenderer = any;
296
+ interface BalanceStrategy {
297
+ type: 'count_balance' | 'timespan_balance';
298
+ transfers: TransferOperation[];
299
+ specialLayoutRules: SpecialLayoutRule[];
300
+ }
301
+ /**
302
+ * Transfer operation interface
303
+ * Describes movement of events in layout optimization
304
+ */
305
+ interface TransferOperation {
306
+ event: Event;
307
+ fromParent: Event;
308
+ toParent: Event;
309
+ reason: string;
310
+ }
311
+ /**
312
+ * Special layout rule interface
313
+ * Defines layout constraints for specific events
314
+ */
315
+ interface SpecialLayoutRule {
316
+ eventId: string;
317
+ layoutType: 'align_with_ancestor' | 'full_width' | 'full_width_from_level' | 'align_with_sibling';
318
+ referenceEvent?: Event;
319
+ targetLevel?: number;
320
+ reason?: string;
321
+ }
231
322
 
232
323
  /** Generic type for framework-specific components */
233
- type TComponent = any;
324
+ type TComponent = AnyComponent<any, any>;
234
325
  /** Generic type for framework-specific nodes/elements */
235
- type TNode = any;
326
+ type TNode = ComponentChildren;
327
+ /**
328
+ * Custom mobile event renderer (Drawer or Dialog)
329
+ */
330
+ type MobileEventRenderer = AnyComponent<any, any>;
236
331
  /**
237
332
  * View type enum
238
333
  */
@@ -298,15 +393,37 @@ interface CalendarCallbacks {
298
393
  onMoreEventsClick?: (date: Date) => void | Promise<void>;
299
394
  onDismissUI?: () => void | Promise<void>;
300
395
  }
396
+ interface TitleBarSlotProps {
397
+ isCollapsed: boolean;
398
+ toggleCollapsed: () => void;
399
+ }
400
+ interface CreateCalendarDialogColorPickerProps {
401
+ color: string;
402
+ onChange: (color: {
403
+ hex: string;
404
+ }) => void;
405
+ onAccept?: () => void;
406
+ onCancel?: () => void;
407
+ styles?: any;
408
+ }
409
+ interface ColorPickerProps {
410
+ color: string;
411
+ onChange: (color: {
412
+ hex: string;
413
+ }) => void;
414
+ onChangeComplete?: (color: {
415
+ hex: string;
416
+ }) => void;
417
+ }
301
418
  interface CreateCalendarDialogProps {
302
419
  onClose: () => void;
303
420
  onCreate: (calendar: CalendarType) => void;
304
- colorPickerMode?: 'default' | 'custom';
421
+ app: ICalendarApp;
305
422
  }
306
423
  interface CalendarHeaderProps {
307
424
  calendar: ICalendarApp;
308
425
  switcherMode?: ViewSwitcherMode;
309
- onAddCalendar?: (e: any) => void;
426
+ onAddCalendar?: (e: h.JSX.TargetedMouseEvent<HTMLElement> | h.JSX.TargetedTouchEvent<HTMLElement>) => void;
310
427
  onSearchChange?: (value: string) => void;
311
428
  /** Triggered when search icon is clicked (typically on mobile) */
312
429
  onSearchClick?: () => void;
@@ -316,6 +433,16 @@ interface CalendarHeaderProps {
316
433
  /** Left safe area padding (px) to avoid overlapping with traffic light buttons in macMode */
317
434
  safeAreaLeft?: number;
318
435
  }
436
+ /** Args passed to all eventContent* slot renderers. */
437
+ interface EventContentSlotArgs {
438
+ event: Event;
439
+ viewType: ViewType;
440
+ isAllDay: boolean;
441
+ isMobile: boolean;
442
+ isSelected: boolean;
443
+ isDragging: boolean;
444
+ layout?: EventLayout;
445
+ }
319
446
  /**
320
447
  * Calendar application configuration
321
448
  * Used to initialize CalendarApp
@@ -359,6 +486,7 @@ interface CalendarAppState {
359
486
  highlightedEventId?: string | null;
360
487
  selectedEventId?: string | null;
361
488
  readOnly: boolean | ReadOnlyConfig;
489
+ overrides: string[];
362
490
  }
363
491
  /**
364
492
  * Calendar application instance
@@ -385,9 +513,9 @@ interface ICalendarApp {
385
513
  updates: Partial<Event>;
386
514
  }>;
387
515
  delete?: string[];
388
- }, isPending?: boolean) => void;
516
+ }, isPending?: boolean, source?: 'drag' | 'resize') => void;
389
517
  addEvent: (event: Event) => void;
390
- updateEvent: (id: string, event: Partial<Event>, isPending?: boolean) => void;
518
+ updateEvent: (id: string, event: Partial<Event>, isPending?: boolean, source?: 'drag' | 'resize') => void;
391
519
  deleteEvent: (id: string) => void;
392
520
  getEvents: () => Event[];
393
521
  getAllEvents: () => Event[];
@@ -415,6 +543,7 @@ interface ICalendarApp {
415
543
  getUseEventDetailDialog: () => boolean;
416
544
  getCustomMobileEventRenderer: () => MobileEventRenderer | undefined;
417
545
  updateConfig: (config: Partial<CalendarAppConfig>) => void;
546
+ setOverrides: (overrides: string[]) => void;
418
547
  setTheme: (mode: ThemeMode) => void;
419
548
  getTheme: () => ThemeMode;
420
549
  subscribeThemeChange: (callback: (theme: ThemeMode) => void) => () => void;
@@ -436,11 +565,11 @@ interface UseCalendarAppReturn {
436
565
  updates: Partial<Event>;
437
566
  }>;
438
567
  delete?: string[];
439
- }, isPending?: boolean) => void;
568
+ }, isPending?: boolean, source?: 'drag' | 'resize') => void;
440
569
  changeView: (view: ViewType) => void;
441
570
  setCurrentDate: (date: Date) => void;
442
571
  addEvent: (event: Event) => void;
443
- updateEvent: (id: string, event: Partial<Event>, isPending?: boolean) => void;
572
+ updateEvent: (id: string, event: Partial<Event>, isPending?: boolean, source?: 'drag' | 'resize') => void;
444
573
  deleteEvent: (id: string) => void;
445
574
  goToToday: () => void;
446
575
  goToPrevious: () => void;
@@ -484,258 +613,47 @@ interface CalendarConfig {
484
613
  month: Record<string, unknown>;
485
614
  };
486
615
  }
487
- interface UseCalendarReturn {
488
- view: ViewType;
489
- currentDate: Date;
490
- events: Event[];
491
- currentWeekStart: Date;
492
- changeView: (view: ViewType) => void;
493
- goToToday: () => void;
494
- goToPrevious: () => void;
495
- goToNext: () => void;
496
- selectDate: (date: Date) => void;
497
- updateEvent: (eventId: string, updates: Partial<Event>, isPending?: boolean) => void;
498
- deleteEvent: (eventId: string) => void;
499
- addEvent: (event: Omit<Event, 'id'>) => void;
500
- setEvents: (events: Event[] | ((prev: Event[]) => Event[])) => void;
501
- }
502
-
503
- /**
504
- * Date data interface
505
- * Represents detailed information for a single date
506
- */
507
- interface DayData {
508
- date: Date;
509
- day: number;
510
- month: number;
511
- year: number;
512
- monthName: string;
513
- shortMonthName: string;
514
- isToday: boolean;
515
- }
516
- /**
517
- * Week data interface
518
- * Represents a week's data, containing date information for 7 days
519
- */
520
- interface WeeksData {
521
- days: DayData[];
522
- startDate: Date;
523
- monthYear: {
524
- month: string;
525
- monthIndex: number;
526
- year: number;
527
- };
528
- }
529
-
530
- /**
531
- * Event layout configuration constants
532
- * Controls visual presentation of events in the calendar
533
- */
534
- declare const LAYOUT_CONFIG: {
535
- readonly INDENT_STEP: 2;
536
- readonly MIN_WIDTH: 25;
537
- readonly MARGIN_BETWEEN: 2;
538
- readonly CONTAINER_WIDTH: 320;
539
- readonly OVERLAP_THRESHOLD: 0.25;
540
- readonly EDGE_MARGIN: 3;
541
- readonly MAX_LOAD_IMBALANCE: 0;
542
- readonly REBALANCE_THRESHOLD: 2;
543
- };
544
- /**
545
- * Event layout interface
546
- * Defines position and styling of events in the UI
547
- */
548
- interface EventLayout {
549
- id: string;
550
- left: number;
551
- width: number;
552
- zIndex: number;
553
- level: number;
554
- isPrimary: boolean;
555
- indentOffset: number;
556
- importance: number;
557
- }
558
- /**
559
- * Nested layer interface
560
- * Represents hierarchical relationships of events
561
- */
562
- interface NestedLayer {
563
- events: Event[];
564
- level: number;
565
- parentEvent?: Event;
566
- timeSlot?: {
567
- start: number;
568
- end: number;
569
- };
570
- }
571
- /**
572
- * Event group interface
573
- * Represents a group of related events and their nested structure
574
- */
575
- interface EventGroup {
576
- events: Event[];
577
- startHour: number;
578
- endHour: number;
579
- primaryEvent?: Event;
580
- nestedStructure: NestedLayer[];
581
- specialLayoutRules?: SpecialLayoutRule[];
582
- originalBranchMap?: Map<string, Event>;
583
- }
584
- /**
585
- * Event relationship information interface
586
- * Describes relationships of events in nested structures
587
- */
588
- interface EventRelations {
589
- directChildren: Event[];
590
- allDescendants: Event[];
591
- directParent: Event | null;
592
- layer: NestedLayer | null;
593
- subtreeSize: number;
594
- isLeaf: boolean;
595
- }
596
- /**
597
- * Subtree analysis interface
598
- * Used to analyze structural information of event trees
599
- */
600
- interface SubtreeAnalysis {
601
- rootEvent: Event;
602
- allDescendants: Event[];
603
- timeSpan: {
604
- start: number;
605
- end: number;
606
- duration: number;
607
- };
608
- descendantCount: number;
609
- maxDepth: number;
610
- branchPath: Event[];
611
- }
612
- /**
613
- * Balance strategy interface
614
- * Used for balance algorithms to optimize event layouts
615
- */
616
- interface BalanceStrategy {
617
- type: 'count_balance' | 'timespan_balance';
618
- transfers: TransferOperation[];
619
- specialLayoutRules: SpecialLayoutRule[];
620
- }
621
- /**
622
- * Transfer operation interface
623
- * Describes movement of events in layout optimization
624
- */
625
- interface TransferOperation {
626
- event: Event;
627
- fromParent: Event;
628
- toParent: Event;
629
- reason: string;
630
- }
631
- /**
632
- * Special layout rule interface
633
- * Defines layout constraints for specific events
634
- */
635
- interface SpecialLayoutRule {
636
- eventId: string;
637
- layoutType: 'align_with_ancestor' | 'full_width' | 'full_width_from_level' | 'align_with_sibling';
638
- referenceEvent?: Event;
639
- targetLevel?: number;
640
- reason?: string;
641
- }
642
-
643
- /**
644
- * Virtual scroll item interface (YearView)
645
- */
646
- interface VirtualItem {
647
- index: number;
648
- year: number;
649
- top: number;
650
- height: number;
651
- }
652
- /**
653
- * Virtual scroll Hook parameters interface (YearView)
654
- */
655
- interface UseVirtualScrollProps {
656
- currentDate: Date;
657
- yearHeight: number;
658
- onCurrentYearChange?: (year: number) => void;
659
- }
660
- /**
661
- * Virtual scroll Hook return value interface (YearView)
662
- */
663
- interface UseVirtualScrollReturn {
664
- scrollTop: number;
665
- containerHeight: number;
666
- currentYear: number;
667
- isScrolling: boolean;
668
- virtualData: {
669
- totalHeight: number;
670
- visibleItems: VirtualItem[];
671
- };
672
- scrollElementRef: any;
673
- handleScroll: (e: any) => void;
674
- scrollToYear: (targetYear: number, smooth?: boolean) => void;
675
- handlePreviousYear: () => void;
676
- handleNextYear: () => void;
677
- handleToday: () => void;
678
- setScrollTop: (val: number | ((prev: number) => number)) => void;
679
- setContainerHeight: (val: number | ((prev: number) => number)) => void;
680
- setCurrentYear: (val: number | ((prev: number) => number)) => void;
681
- setIsScrolling: (val: boolean | ((prev: boolean) => boolean)) => void;
682
- }
683
- /**
684
- * Drag state Hook return value
685
- */
686
- interface UseDragStateReturn {
687
- dragRef: RefObject<UnifiedDragRef>;
688
- currentDragRef: RefObject<{
689
- x: number;
690
- y: number;
691
- }>;
692
- dragState: MonthDragState | WeekDayDragState;
693
- setDragState: (val: MonthDragState | WeekDayDragState | ((prev: MonthDragState | WeekDayDragState) => MonthDragState | WeekDayDragState)) => void;
694
- resetDragState: () => void;
695
- throttledSetEvents: (updateFunc: (events: Event[]) => Event[], dragState?: string) => void;
696
- }
697
- /**
698
- * Drag common utilities Hook return value
699
- */
700
- interface UseDragCommonReturn {
701
- pixelYToHour: (y: number) => number;
702
- getColumnDayIndex: (x: number) => number;
703
- checkIfInAllDayArea: (clientY: number) => boolean;
704
- handleDirectScroll: (clientY: number) => void;
705
- daysDifference: (date1: Date, date2: Date) => number;
706
- addDaysToDate: (date: Date, days: number) => Date;
707
- getTargetDateFromPosition: (clientX: number, clientY: number) => Date | null;
708
- ONE_DAY_MS: number;
709
- }
710
- /**
711
- * Drag management Hook return value
712
- */
713
- interface UseDragManagerReturn {
714
- dragIndicatorRef: RefObject<HTMLDivElement | null>;
715
- removeDragIndicator: () => void;
716
- createDragIndicator: (drag: UnifiedDragRef, color?: string, title?: string, layout?: EventLayout | null, sourceElement?: HTMLElement) => void;
717
- updateDragIndicator: (...args: (number | boolean | EventLayout | null | undefined)[]) => void;
616
+ interface UseCalendarReturn {
617
+ view: ViewType;
618
+ currentDate: Date;
619
+ events: Event[];
620
+ currentWeekStart: Date;
621
+ changeView: (view: ViewType) => void;
622
+ goToToday: () => void;
623
+ goToPrevious: () => void;
624
+ goToNext: () => void;
625
+ selectDate: (date: Date) => void;
626
+ updateEvent: (eventId: string, updates: Partial<Event>, isPending?: boolean) => void;
627
+ deleteEvent: (eventId: string) => void;
628
+ addEvent: (event: Omit<Event, 'id'>) => void;
629
+ setEvents: (events: Event[] | ((prev: Event[]) => Event[])) => void;
718
630
  }
631
+
719
632
  /**
720
- * Drag handler Hook return value
633
+ * Date data interface
634
+ * Represents detailed information for a single date
721
635
  */
722
- interface UseDragHandlersReturn {
723
- handleDragMove: (e: MouseEvent | TouchEvent) => void;
724
- handleDragEnd: (e: MouseEvent | TouchEvent) => void;
725
- handleCreateStart: (e: any | any, ...args: (Date | number)[]) => void;
726
- handleMoveStart: (e: any | any, event: Event) => void;
727
- handleResizeStart: (e: any | any, event: Event, direction: string) => void;
728
- handleUniversalDragMove: (e: MouseEvent | TouchEvent) => void;
729
- handleUniversalDragEnd: (e?: MouseEvent | TouchEvent) => void;
636
+ interface DayData {
637
+ date: Date;
638
+ day: number;
639
+ month: number;
640
+ year: number;
641
+ monthName: string;
642
+ shortMonthName: string;
643
+ isToday: boolean;
730
644
  }
731
645
  /**
732
- * Drag handler Hook parameters
646
+ * Week data interface
647
+ * Represents a week's data, containing date information for 7 days
733
648
  */
734
- interface UseDragHandlersParams {
735
- options: useDragProps;
736
- common: UseDragCommonReturn;
737
- state: UseDragStateReturn;
738
- manager: UseDragManagerReturn;
649
+ interface WeeksData {
650
+ days: DayData[];
651
+ startDate: Date;
652
+ monthYear: {
653
+ month: string;
654
+ monthIndex: number;
655
+ year: number;
656
+ };
739
657
  }
740
658
 
741
659
  /**
@@ -792,15 +710,16 @@ interface DragIndicatorProps {
792
710
  isMobile?: boolean;
793
711
  }
794
712
  interface DragIndicatorRenderer {
795
- renderAllDayContent: (props: DragIndicatorProps) => any;
796
- renderRegularContent: (props: DragIndicatorProps) => any;
797
- renderDefaultContent: (props: DragIndicatorProps) => any;
713
+ renderAllDayContent: (props: DragIndicatorProps) => ComponentChildren;
714
+ renderRegularContent: (props: DragIndicatorProps) => ComponentChildren;
715
+ renderDefaultContent: (props: DragIndicatorProps) => ComponentChildren;
798
716
  }
799
717
  interface UnifiedDragRef extends DragRef {
800
718
  targetDate?: Date | null;
801
719
  originalDate?: Date | null;
802
720
  originalEvent?: Event | null;
803
721
  dragOffset?: number;
722
+ dragOffsetY?: number;
804
723
  originalStartDate?: Date | null;
805
724
  originalEndDate?: Date | null;
806
725
  eventDate?: Date;
@@ -823,9 +742,11 @@ interface UnifiedDragRef extends DragRef {
823
742
  title?: string;
824
743
  }
825
744
  interface useDragProps extends Partial<DragConfig> {
826
- calendarRef: any;
827
- allDayRowRef?: any;
828
- onEventsUpdate: (updateFunc: (events: Event[]) => Event[], isResizing?: boolean) => void;
745
+ calendarRef: RefObject<HTMLDivElement>;
746
+ allDayRowRef?: RefObject<HTMLDivElement>;
747
+ timeGridRef?: RefObject<HTMLDivElement>;
748
+ viewType: ViewType;
749
+ onEventsUpdate: (updateFunc: (events: Event[]) => Event[], isResizing?: boolean, source?: 'drag' | 'resize') => void;
829
750
  onEventCreate: (event: Event) => void;
830
751
  onEventEdit?: (event: Event) => void;
831
752
  calculateNewEventLayout?: (dayIndex: number, startHour: number, endHour: number) => EventLayout | null;
@@ -835,6 +756,8 @@ interface useDragProps extends Partial<DragConfig> {
835
756
  renderer?: DragIndicatorRenderer;
836
757
  app?: ICalendarApp;
837
758
  isMobile?: boolean;
759
+ gridWidth?: string;
760
+ displayDays?: number;
838
761
  }
839
762
  type MonthDragState = {
840
763
  active: boolean;
@@ -857,10 +780,10 @@ interface useDragReturn {
857
780
  createDragIndicator: (drag: UnifiedDragRef, color?: string, title?: string, layout?: EventLayout | null, sourceElement?: HTMLElement) => void;
858
781
  updateDragIndicator: (...args: (number | boolean | EventLayout | null | undefined)[]) => void;
859
782
  removeDragIndicator: () => void;
860
- handleCreateAllDayEvent?: (e: any, dayIndex: number) => void;
861
- handleCreateStart: (e: any | any, ...args: (Date | number)[]) => void;
862
- handleMoveStart: (e: any | any, event: Event) => void;
863
- handleResizeStart: (e: any | any, event: Event, direction: string) => void;
783
+ handleCreateAllDayEvent?: (e: MouseEvent | TouchEvent, dayIndex: number) => void;
784
+ handleCreateStart: (e: MouseEvent | TouchEvent, ...args: (Date | number)[]) => void;
785
+ handleMoveStart: (e: MouseEvent | TouchEvent, event: Event) => void;
786
+ handleResizeStart: (e: MouseEvent | TouchEvent, event: Event, direction: string) => void;
864
787
  dragState: MonthDragState | WeekDayDragState;
865
788
  isDragging: boolean;
866
789
  pixelYToHour?: (y: number) => number;
@@ -870,6 +793,63 @@ interface useDragReturn {
870
793
  * Month view event drag state (alias for MonthDragState, maintains backward compatibility)
871
794
  */
872
795
  type MonthEventDragState = MonthDragState;
796
+ /**
797
+ * Drag state Hook return value
798
+ */
799
+ interface UseDragStateReturn {
800
+ dragRef: RefObject<UnifiedDragRef>;
801
+ currentDragRef: RefObject<{
802
+ x: number;
803
+ y: number;
804
+ }>;
805
+ dragState: MonthDragState | WeekDayDragState;
806
+ setDragState: (val: MonthDragState | WeekDayDragState | ((prev: MonthDragState | WeekDayDragState) => MonthDragState | WeekDayDragState)) => void;
807
+ resetDragState: () => void;
808
+ throttledSetEvents: (updateFunc: (events: Event[]) => Event[], dragState?: string) => void;
809
+ }
810
+ /**
811
+ * Drag common utilities Hook return value
812
+ */
813
+ interface UseDragCommonReturn {
814
+ pixelYToHour: (y: number) => number;
815
+ getColumnDayIndex: (x: number) => number;
816
+ checkIfInAllDayArea: (clientY: number) => boolean;
817
+ handleDirectScroll: (clientY: number) => void;
818
+ daysDifference: (date1: Date, date2: Date) => number;
819
+ addDaysToDate: (date: Date, days: number) => Date;
820
+ getTargetDateFromPosition: (clientX: number, clientY: number) => Date | null;
821
+ ONE_DAY_MS: number;
822
+ }
823
+ /**
824
+ * Drag management Hook return value
825
+ */
826
+ interface UseDragManagerReturn {
827
+ dragIndicatorRef: RefObject<HTMLDivElement | null>;
828
+ removeDragIndicator: () => void;
829
+ createDragIndicator: (drag: UnifiedDragRef, color?: string, title?: string, layout?: EventLayout | null, sourceElement?: HTMLElement) => void;
830
+ updateDragIndicator: (...args: (number | boolean | EventLayout | null | undefined)[]) => void;
831
+ }
832
+ /**
833
+ * Drag handler Hook return value
834
+ */
835
+ interface UseDragHandlersReturn {
836
+ handleDragMove: (e: MouseEvent | TouchEvent) => void;
837
+ handleDragEnd: (e: MouseEvent | TouchEvent) => void;
838
+ handleCreateStart: (e: MouseEvent | TouchEvent, ...args: (Date | number)[]) => void;
839
+ handleMoveStart: (e: MouseEvent | TouchEvent, event: Event) => void;
840
+ handleResizeStart: (e: MouseEvent | TouchEvent, event: Event, direction: string) => void;
841
+ handleUniversalDragMove: (e: MouseEvent | TouchEvent) => void;
842
+ handleUniversalDragEnd: (e?: MouseEvent | TouchEvent) => void;
843
+ }
844
+ /**
845
+ * Drag handler Hook parameters
846
+ */
847
+ interface UseDragHandlersParams {
848
+ options: useDragProps;
849
+ common: UseDragCommonReturn;
850
+ state: UseDragStateReturn;
851
+ manager: UseDragManagerReturn;
852
+ }
873
853
  interface UseMonthDragReturn {
874
854
  daysDifference: (date1: Date, date2: Date) => number;
875
855
  addDaysToDate: (date: Date, days: number) => Date;
@@ -882,7 +862,7 @@ interface UseMonthDragParams {
882
862
  manager: UseDragManagerReturn;
883
863
  }
884
864
  interface UseWeekDayDragReturn {
885
- handleCreateAllDayEvent: (e: any, dayIndex: number) => void;
865
+ handleCreateAllDayEvent: (e: MouseEvent | TouchEvent, dayIndex: number) => void;
886
866
  pixelYToHour: (y: number) => number;
887
867
  getColumnDayIndex: (x: number) => number;
888
868
  }
@@ -901,6 +881,7 @@ interface UseVirtualMonthScrollProps {
901
881
  onCurrentMonthChange?: (month: string, year: number) => void;
902
882
  initialWeeksToLoad?: number;
903
883
  locale?: string;
884
+ startOfWeek?: number;
904
885
  isEnabled?: boolean;
905
886
  }
906
887
  interface UseVirtualMonthScrollReturn {
@@ -915,17 +896,17 @@ interface UseVirtualMonthScrollReturn {
915
896
  visibleItems: VirtualWeekItem[];
916
897
  displayStartIndex: number;
917
898
  };
918
- scrollElementRef: any;
919
- handleScroll: (e: any) => void;
899
+ scrollElementRef: RefObject<HTMLDivElement>;
900
+ handleScroll: (e: JSX.TargetedEvent<HTMLDivElement, globalThis.Event>) => void;
920
901
  scrollToDate: (targetDate: Date, smooth?: boolean) => void;
921
902
  handlePreviousMonth: () => void;
922
903
  handleNextMonth: () => void;
923
904
  handleToday: () => void;
924
- setScrollTop: React.Dispatch<React.SetStateAction<number>>;
925
- setContainerHeight: React.Dispatch<React.SetStateAction<number>>;
926
- setCurrentMonth: React.Dispatch<React.SetStateAction<string>>;
927
- setCurrentYear: React.Dispatch<React.SetStateAction<number>>;
928
- setIsScrolling: React.Dispatch<React.SetStateAction<boolean>>;
905
+ setScrollTop: (val: number | ((prev: number) => number)) => void;
906
+ setContainerHeight: (val: number | ((prev: number) => number)) => void;
907
+ setCurrentMonth: (val: string | ((prev: string) => string)) => void;
908
+ setCurrentYear: (val: number | ((prev: number) => number)) => void;
909
+ setIsScrolling: (val: boolean | ((prev: boolean) => boolean)) => void;
929
910
  cache: WeekDataCache;
930
911
  scrollElementRefCallback: (element: HTMLDivElement | null) => void;
931
912
  weeksData: WeeksData[];
@@ -953,7 +934,7 @@ declare class WeekDataCache {
953
934
  private accessOrder;
954
935
  private maxSize;
955
936
  constructor(maxSize?: number);
956
- private getKey;
937
+ private static getKey;
957
938
  get(weekStartDate: Date): WeeksData | undefined;
958
939
  set(weekStartDate: Date, data: WeeksData): void;
959
940
  private updateAccessOrder;
@@ -970,15 +951,15 @@ interface EventDetailPanelProps {
970
951
  /** Panel position information */
971
952
  position: EventDetailPosition;
972
953
  /** Panel DOM reference */
973
- panelRef: any;
954
+ panelRef: RefObject<HTMLDivElement>;
974
955
  /** Whether the event is all-day */
975
956
  isAllDay: boolean;
976
957
  /** Event visibility state */
977
958
  eventVisibility: 'visible' | 'sticky-top' | 'sticky-bottom';
978
959
  /** Calendar container reference */
979
- calendarRef: any;
960
+ calendarRef: RefObject<HTMLDivElement>;
980
961
  /** Selected event element reference */
981
- selectedEventElementRef: any;
962
+ selectedEventElementRef: RefObject<HTMLElement | null>;
982
963
  /** Event update callback */
983
964
  onEventUpdate: (updatedEvent: Event) => void;
984
965
  /** Event delete callback */
@@ -989,7 +970,7 @@ interface EventDetailPanelProps {
989
970
  /**
990
971
  * Custom event detail panel renderer (full panel including positioning and styling)
991
972
  */
992
- type EventDetailPanelRenderer = any;
973
+ type EventDetailPanelRenderer = AnyComponent<EventDetailPanelProps, any>;
993
974
  /**
994
975
  * Event detail content Props (excluding panel container, content only)
995
976
  */
@@ -1004,11 +985,12 @@ interface EventDetailContentProps {
1004
985
  onEventDelete: (eventId: string) => void;
1005
986
  /** Close panel callback (optional) */
1006
987
  onClose?: () => void;
988
+ app?: ICalendarApp;
1007
989
  }
1008
990
  /**
1009
991
  * Custom event detail content renderer (content only, will be wrapped in default panel)
1010
992
  */
1011
- type EventDetailContentRenderer = any;
993
+ type EventDetailContentRenderer = AnyComponent<EventDetailContentProps, any>;
1012
994
  /**
1013
995
  * Event detail dialog Props
1014
996
  */
@@ -1030,13 +1012,146 @@ interface EventDetailDialogProps {
1030
1012
  /**
1031
1013
  * Custom event detail dialog renderer (Dialog/Modal mode)
1032
1014
  */
1033
- type EventDetailDialogRenderer = any;
1015
+ type EventDetailDialogRenderer = AnyComponent<EventDetailDialogProps, any>;
1016
+
1017
+ /**
1018
+ * Common IANA TimeZone identifiers.
1019
+ * This enum provides a convenient way for users to specify secondary timezones
1020
+ * without having to look up the exact Temporal/Intl TimeZone strings.
1021
+ */
1022
+ declare enum TimeZone {
1023
+ UTC = "UTC",
1024
+ NEW_YORK = "America/New_York",
1025
+ CHICAGO = "America/Chicago",
1026
+ DENVER = "America/Denver",
1027
+ LOS_ANGELES = "America/Los_Angeles",
1028
+ TORONTO = "America/Toronto",
1029
+ VANCOUVER = "America/Vancouver",
1030
+ PHOENIX = "America/Phoenix",
1031
+ ANCHORAGE = "America/Anchorage",
1032
+ HONOLULU = "Pacific/Honolulu",
1033
+ MEXICO_CITY = "America/Mexico_City",
1034
+ WINNIPEG = "America/Winnipeg",
1035
+ HALIFAX = "America/Halifax",
1036
+ ST_JOHNS = "America/St_Johns",
1037
+ DETROIT = "America/Detroit",
1038
+ MIAMI = "America/Miami",
1039
+ SEATTLE = "America/Los_Angeles",
1040
+ ATLANTA = "America/New_York",
1041
+ DALLAS = "America/Chicago",
1042
+ HOUSTON = "America/Chicago",
1043
+ LAS_VEGAS = "America/Los_Angeles",
1044
+ SAN_FRANCISCO = "America/Los_Angeles",
1045
+ LONDON = "Europe/London",
1046
+ PARIS = "Europe/Paris",
1047
+ BERLIN = "Europe/Berlin",
1048
+ MADRID = "Europe/Madrid",
1049
+ ROME = "Europe/Rome",
1050
+ AMSTERDAM = "Europe/Amsterdam",
1051
+ ZURICH = "Europe/Zurich",
1052
+ STOCKHOLM = "Europe/Stockholm",
1053
+ OSLO = "Europe/Oslo",
1054
+ COPENHAGEN = "Europe/Copenhagen",
1055
+ MOSCOW = "Europe/Moscow",
1056
+ ISTANBUL = "Europe/Istanbul",
1057
+ DUBLIN = "Europe/Dublin",
1058
+ LISBON = "Europe/Lisbon",
1059
+ PRAGUE = "Europe/Prague",
1060
+ VIENNA = "Europe/Vienna",
1061
+ WARSAW = "Europe/Warsaw",
1062
+ BRUSSELS = "Europe/Brussels",
1063
+ ATHENS = "Europe/Athens",
1064
+ BUCHAREST = "Europe/Bucharest",
1065
+ HELSINKI = "Europe/Helsinki",
1066
+ KYIV = "Europe/Kyiv",
1067
+ BUDAPEST = "Europe/Budapest",
1068
+ BELGRADE = "Europe/Belgrade",
1069
+ LUXEMBOURG = "Europe/Luxembourg",
1070
+ MONACO = "Europe/Monaco",
1071
+ REYKJAVIK = "Atlantic/Reykjavik",
1072
+ TOKYO = "Asia/Tokyo",
1073
+ SHANGHAI = "Asia/Shanghai",
1074
+ BEIJING = "Asia/Shanghai",
1075
+ HONG_KONG = "Asia/Hong_Kong",
1076
+ TAIPEI = "Asia/Taipei",
1077
+ SEOUL = "Asia/Seoul",
1078
+ SINGAPORE = "Asia/Singapore",
1079
+ HANOI = "Asia/Ho_Chi_Minh",
1080
+ BANGKOK = "Asia/Bangkok",
1081
+ JAKARTA = "Asia/Jakarta",
1082
+ KUALA_LUMPUR = "Asia/Kuala_Lumpur",
1083
+ MANILA = "Asia/Manila",
1084
+ DUBAI = "Asia/Dubai",
1085
+ KOLKATA = "Asia/Kolkata",
1086
+ MUMBAI = "Asia/Kolkata",
1087
+ RIYADH = "Asia/Riyadh",
1088
+ TEHRAN = "Asia/Tehran",
1089
+ JERUSALEM = "Asia/Jerusalem",
1090
+ TEL_AVIV = "Asia/Tel_Aviv",
1091
+ BAGHDAD = "Asia/Baghdad",
1092
+ DHAKA = "Asia/Dhaka",
1093
+ KARA_CHI = "Asia/Karachi",
1094
+ KABUL = "Asia/Kabul",
1095
+ KATHMANDU = "Asia/Kathmandu",
1096
+ COLOMBO = "Asia/Colombo",
1097
+ TASHKENT = "Asia/Tashkent",
1098
+ ALMATY = "Asia/Almaty",
1099
+ PHNOM_PENH = "Asia/Phnom_Penh",
1100
+ VIENTIANE = "Asia/Vientiane",
1101
+ MUSCAT = "Asia/Muscat",
1102
+ SYDNEY = "Australia/Sydney",
1103
+ MELBOURNE = "Australia/Melbourne",
1104
+ BRISBANE = "Australia/Brisbane",
1105
+ PERTH = "Australia/Perth",
1106
+ ADELAIDE = "Australia/Adelaide",
1107
+ DARWIN = "Australia/Darwin",
1108
+ HOBART = "Australia/Hobart",
1109
+ AUCKLAND = "Pacific/Auckland",
1110
+ FIJI = "Pacific/Fiji",
1111
+ GUAM = "Pacific/Guam",
1112
+ NOUMEA = "Pacific/Noumea",
1113
+ PAGO_PAGO = "Pacific/Pago_Pago",
1114
+ PORT_MORESBY = "Pacific/Port_Moresby",
1115
+ SAO_PAULO = "America/Sao_Paulo",
1116
+ RIO_DE_JANEIRO = "America/Sao_Paulo",
1117
+ BUENOS_AIRES = "America/Argentina/Buenos_Aires",
1118
+ SANTIAGO = "America/Santiago",
1119
+ LIMA = "America/Lima",
1120
+ BOGOTA = "America/Bogota",
1121
+ CARACAS = "America/Caracas",
1122
+ LA_PAZ = "America/La_Paz",
1123
+ MONTEVIDEO = "America/Montevideo",
1124
+ QUITO = "America/Quito",
1125
+ ASUNCION = "America/Asuncion",
1126
+ GEORGETOWN = "America/Guyana",
1127
+ CAIRO = "Africa/Cairo",
1128
+ JOHANNESBURG = "Africa/Johannesburg",
1129
+ LAGOS = "Africa/Lagos",
1130
+ NAIROBI = "Africa/Nairobi",
1131
+ CASABLANCA = "Africa/Casablanca",
1132
+ ALGIERS = "Africa/Algiers",
1133
+ TUNIS = "Africa/Tunis",
1134
+ ADDIS_ABABA = "Africa/Addis_Ababa",
1135
+ ACCRA = "Africa/Accra",
1136
+ DAKAR = "Africa/Dakar",
1137
+ LUANDA = "Africa/Luanda",
1138
+ ANTANANARIVO = "Indian/Antananarivo",
1139
+ KINSHASA = "Africa/Kinshasa",
1140
+ DAR_ES_SALAAM = "Africa/Dar_es_Salaam",
1141
+ MCMURDO = "Antarctica/McMurdo",
1142
+ CASEY = "Antarctica/Casey"
1143
+ }
1144
+ /**
1145
+ * Type helper for secondaryTimeZone configuration
1146
+ * Allows using either the TimeZone enum or a raw IANA string.
1147
+ */
1148
+ type TimeZoneValue = TimeZone | string;
1034
1149
 
1035
1150
  /**
1036
1151
  * Common Props interface for view components
1037
1152
  * Base properties for all view components
1038
1153
  */
1039
- interface BaseViewProps<TConfig = any> {
1154
+ interface BaseViewProps<TConfig = unknown> {
1040
1155
  app: ICalendarApp;
1041
1156
  currentDate?: Date;
1042
1157
  currentView?: ViewType;
@@ -1053,57 +1168,44 @@ interface BaseViewProps<TConfig = any> {
1053
1168
  onDetailPanelToggle?: (eventId: string | null) => void;
1054
1169
  customDetailPanelContent?: EventDetailContentRenderer;
1055
1170
  customEventDetailDialog?: EventDetailDialogRenderer;
1056
- calendarRef: any;
1171
+ calendarRef: RefObject<HTMLDivElement>;
1057
1172
  switcherMode?: ViewSwitcherMode;
1058
- meta?: Record<string, any>;
1173
+ meta?: Record<string, unknown>;
1059
1174
  }
1060
1175
  /**
1061
1176
  * Day view specific Props
1062
1177
  */
1063
- interface DayViewProps extends BaseViewProps<DayViewConfig> {
1064
- }
1178
+ type DayViewProps = BaseViewProps<DayViewConfig>;
1065
1179
  /**
1066
1180
  * Week view specific Props
1067
1181
  */
1068
- interface WeekViewProps extends BaseViewProps<WeekViewConfig> {
1069
- }
1182
+ type WeekViewProps = BaseViewProps<WeekViewConfig>;
1070
1183
  /**
1071
1184
  * Month view specific Props
1072
1185
  */
1073
- interface MonthViewProps extends BaseViewProps<MonthViewConfig> {
1074
- }
1186
+ type MonthViewProps = BaseViewProps<MonthViewConfig>;
1075
1187
  /**
1076
1188
  * Year view specific Props
1077
1189
  */
1078
- interface YearViewProps extends BaseViewProps<YearViewConfig> {
1079
- }
1190
+ type YearViewProps = BaseViewProps<YearViewConfig>;
1080
1191
  /**
1081
1192
  * View factory configuration interface
1082
1193
  * Base configuration for creating views
1083
1194
  */
1084
1195
  interface ViewFactoryConfig {
1085
- enableDrag?: boolean;
1086
- enableResize?: boolean;
1087
- enableCreate?: boolean;
1088
- dragConfig?: Record<string, any>;
1089
- eventsConfig?: Record<string, any>;
1090
- virtualScrollConfig?: Record<string, any>;
1091
- viewConfig?: Record<string, any>;
1196
+ hourHeight?: number;
1197
+ firstHour?: number;
1198
+ lastHour?: number;
1199
+ allDayHeight?: number;
1200
+ timeFormat?: '12h' | '24h';
1092
1201
  }
1093
1202
  /**
1094
1203
  * Day view factory configuration
1095
1204
  */
1096
1205
  interface DayViewConfig extends ViewFactoryConfig {
1097
- showMiniCalendar?: boolean;
1098
1206
  showAllDay?: boolean;
1099
1207
  scrollToCurrentTime?: boolean;
1100
- hourHeight?: number;
1101
- firstHour?: number;
1102
- lastHour?: number;
1103
- HOUR_HEIGHT?: number;
1104
- FIRST_HOUR?: number;
1105
- LAST_HOUR?: number;
1106
- ALL_DAY_HEIGHT?: number;
1208
+ secondaryTimeZone?: TimeZoneValue;
1107
1209
  }
1108
1210
  /**
1109
1211
  * Week view factory configuration
@@ -1113,32 +1215,23 @@ interface WeekViewConfig extends ViewFactoryConfig {
1113
1215
  showAllDay?: boolean;
1114
1216
  startOfWeek?: number;
1115
1217
  scrollToCurrentTime?: boolean;
1116
- hourHeight?: number;
1117
- firstHour?: number;
1118
- lastHour?: number;
1119
- HOUR_HEIGHT?: number;
1120
- FIRST_HOUR?: number;
1121
- LAST_HOUR?: number;
1122
- ALL_DAY_HEIGHT?: number;
1218
+ secondaryTimeZone?: TimeZoneValue;
1123
1219
  }
1124
1220
  /**
1125
1221
  * Month view factory configuration
1126
1222
  */
1127
1223
  interface MonthViewConfig extends ViewFactoryConfig {
1128
- showOtherMonth?: boolean;
1129
- weekHeight?: number;
1130
1224
  showWeekNumbers?: boolean;
1131
- enableVirtualScroll?: boolean;
1132
- initialWeeksToLoad?: number;
1225
+ showMonthIndicator?: boolean;
1226
+ startOfWeek?: number;
1133
1227
  }
1134
1228
  /**
1135
1229
  * Year view factory configuration
1136
1230
  */
1137
1231
  interface YearViewConfig extends ViewFactoryConfig {
1138
- enableVirtualScroll?: boolean;
1139
- showDebugInfo?: boolean;
1140
1232
  mode?: 'year-canvas' | 'fixed-week';
1141
1233
  showTimedEventsInYearView?: boolean;
1234
+ startOfWeek?: number;
1142
1235
  }
1143
1236
  /**
1144
1237
  * View adapter Props
@@ -1146,7 +1239,7 @@ interface YearViewConfig extends ViewFactoryConfig {
1146
1239
  */
1147
1240
  interface ViewAdapterProps extends BaseViewProps {
1148
1241
  viewType: ViewType;
1149
- originalComponent: any;
1242
+ originalComponent: AnyComponent<any, any>;
1150
1243
  config: ViewFactoryConfig;
1151
1244
  className?: string;
1152
1245
  }
@@ -1157,8 +1250,8 @@ interface ViewAdapterProps extends BaseViewProps {
1157
1250
  interface DragIntegrationProps {
1158
1251
  app: ICalendarApp;
1159
1252
  viewType: ViewType;
1160
- calendarRef: any;
1161
- allDayRowRef?: any;
1253
+ calendarRef: RefObject<HTMLDivElement>;
1254
+ allDayRowRef?: RefObject<HTMLDivElement>;
1162
1255
  events: Event[];
1163
1256
  onEventsUpdate: (updateFunc: (events: Event[]) => Event[]) => void;
1164
1257
  onEventCreate: (event: Event) => void;
@@ -1235,10 +1328,10 @@ interface EventsPluginConfig {
1235
1328
  * Drag Hook options
1236
1329
  */
1237
1330
  interface DragHookOptions extends Partial<DragConfig> {
1238
- calendarRef: any;
1239
- allDayRowRef?: any;
1331
+ calendarRef: unknown;
1332
+ allDayRowRef?: unknown;
1240
1333
  viewType: ViewType;
1241
- onEventsUpdate: (updateFunc: (events: Event[]) => Event[], isResizing?: boolean) => void;
1334
+ onEventsUpdate: (updateFunc: (events: Event[]) => Event[], isResizing?: boolean, source?: 'drag' | 'resize') => void;
1242
1335
  onEventCreate: (event: Event) => void;
1243
1336
  onEventEdit: (event: Event) => void;
1244
1337
  currentWeekStart: Date;
@@ -1246,15 +1339,18 @@ interface DragHookOptions extends Partial<DragConfig> {
1246
1339
  calculateNewEventLayout?: (dayIndex: number, startHour: number, endHour: number) => EventLayout | null;
1247
1340
  calculateDragLayout?: (event: Event, targetDay: number, targetStartHour: number, targetEndHour: number) => EventLayout | null;
1248
1341
  isMobile?: boolean;
1342
+ timeGridRef?: unknown;
1343
+ gridWidth?: string;
1344
+ displayDays?: number;
1249
1345
  }
1250
1346
  /**
1251
1347
  * Drag Hook return value
1252
1348
  */
1253
1349
  interface DragHookReturn {
1254
- handleMoveStart?: (e: any | any, event: Event) => void;
1255
- handleCreateStart?: (e: any | any, ...args: (Date | number)[]) => void;
1256
- handleResizeStart?: (e: any | any, event: Event, direction: string) => void;
1257
- handleCreateAllDayEvent?: (e: any, dayIndex: number) => void;
1350
+ handleMoveStart?: (e: unknown, event: Event) => void;
1351
+ handleCreateStart?: (e: unknown, ...args: (Date | number)[]) => void;
1352
+ handleResizeStart?: (e: unknown, event: Event, direction: string) => void;
1353
+ handleCreateAllDayEvent?: (e: unknown, dayIndex: number) => void;
1258
1354
  dragState: MonthDragState | WeekDayDragState;
1259
1355
  isDragging: boolean;
1260
1356
  }
@@ -1267,6 +1363,8 @@ interface DragPluginConfig {
1267
1363
  enableCreate: boolean;
1268
1364
  enableAllDayCreate: boolean;
1269
1365
  supportedViews: ViewType[];
1366
+ onEventDrop?: (updatedEvent: Event, originalEvent: Event) => void | Promise<void>;
1367
+ onEventResize?: (updatedEvent: Event, originalEvent: Event) => void | Promise<void>;
1270
1368
  [key: string]: unknown;
1271
1369
  }
1272
1370
  /**
@@ -1279,6 +1377,71 @@ interface DragService {
1279
1377
  isViewSupported: (viewType: ViewType) => boolean;
1280
1378
  }
1281
1379
 
1380
+ /**
1381
+ * Virtual scroll item interface (YearView)
1382
+ */
1383
+ interface VirtualItem {
1384
+ index: number;
1385
+ year: number;
1386
+ top: number;
1387
+ height: number;
1388
+ }
1389
+ /**
1390
+ * Virtual scroll Hook parameters interface (YearView)
1391
+ */
1392
+ interface UseVirtualScrollProps {
1393
+ currentDate: Date;
1394
+ yearHeight: number;
1395
+ onCurrentYearChange?: (year: number) => void;
1396
+ }
1397
+
1398
+ /**
1399
+ * Virtual scroll item interface (YearView)
1400
+ */
1401
+ /**
1402
+ * Virtual scroll Hook return value interface (YearView)
1403
+ */
1404
+ interface UseVirtualScrollReturn {
1405
+ scrollTop: number;
1406
+ containerHeight: number;
1407
+ currentYear: number;
1408
+ isScrolling: boolean;
1409
+ virtualData: {
1410
+ totalHeight: number;
1411
+ visibleItems: VirtualItem[];
1412
+ };
1413
+ scrollElementRef: RefObject<HTMLDivElement>;
1414
+ handleScroll: (e: JSX.TargetedEvent<HTMLDivElement, globalThis.Event>) => void;
1415
+ scrollToYear: (targetYear: number, smooth?: boolean) => void;
1416
+ handlePreviousYear: () => void;
1417
+ handleNextYear: () => void;
1418
+ handleToday: () => void;
1419
+ setScrollTop: (val: number | ((prev: number) => number)) => void;
1420
+ setContainerHeight: (val: number | ((prev: number) => number)) => void;
1421
+ setCurrentYear: (val: number | ((prev: number) => number)) => void;
1422
+ setIsScrolling: (val: boolean | ((prev: boolean) => boolean)) => void;
1423
+ }
1424
+
1425
+ /**
1426
+ * Mobile event drawer/dialog Props
1427
+ */
1428
+ interface MobileEventProps {
1429
+ /** Whether the drawer/dialog is open */
1430
+ isOpen: boolean;
1431
+ /** Callback to close the drawer/dialog */
1432
+ onClose: () => void;
1433
+ /** Callback to save the event (creates or updates) */
1434
+ onSave: (event: Event) => void;
1435
+ /** Callback to delete an existing event by id */
1436
+ onEventDelete?: (id: string) => void;
1437
+ /** Current event data (newly created template or existing event) */
1438
+ draftEvent: Event | null;
1439
+ /** The ICalendarApp instance providing built-in services */
1440
+ app: ICalendarApp;
1441
+ /** Time format for event display */
1442
+ timeFormat?: '12h' | '24h';
1443
+ }
1444
+
1282
1445
  declare class CalendarApp implements ICalendarApp {
1283
1446
  state: CalendarAppState;
1284
1447
  private callbacks;
@@ -1292,10 +1455,11 @@ declare class CalendarApp implements ICalendarApp {
1292
1455
  private listeners;
1293
1456
  private undoStack;
1294
1457
  private pendingSnapshot;
1458
+ private pendingChangeSource;
1295
1459
  private readonly MAX_UNDO_STACK;
1296
1460
  constructor(config: CalendarAppConfig);
1297
1461
  private setupStoreListeners;
1298
- private resolveLocale;
1462
+ private static resolveLocale;
1299
1463
  subscribe: (listener: (app: ICalendarApp) => void) => (() => void);
1300
1464
  private notify;
1301
1465
  private pushToUndo;
@@ -1325,9 +1489,9 @@ declare class CalendarApp implements ICalendarApp {
1325
1489
  updates: Partial<Event>;
1326
1490
  }>;
1327
1491
  delete?: string[];
1328
- }, isPending?: boolean) => void;
1492
+ }, isPending?: boolean, source?: "drag" | "resize") => void;
1329
1493
  addEvent: (event: Event) => void;
1330
- updateEvent: (id: string, eventUpdate: Partial<Event>, isPending?: boolean) => void;
1494
+ updateEvent: (id: string, eventUpdate: Partial<Event>, isPending?: boolean, source?: "drag" | "resize") => void;
1331
1495
  deleteEvent: (id: string) => void;
1332
1496
  getAllEvents: () => Event[];
1333
1497
  onEventClick: (event: Event) => void;
@@ -1344,7 +1508,7 @@ declare class CalendarApp implements ICalendarApp {
1344
1508
  createCalendar: (calendar: CalendarType) => void;
1345
1509
  deleteCalendar: (id: string) => void;
1346
1510
  mergeCalendars: (sourceId: string, targetId: string) => void;
1347
- getCalendarHeaderConfig: () => boolean | ((props: any) => TNode);
1511
+ getCalendarHeaderConfig: () => boolean | ((props: CalendarHeaderProps) => TNode);
1348
1512
  private installPlugin;
1349
1513
  getPlugin: <T = unknown>(name: string) => T | undefined;
1350
1514
  hasPlugin: (name: string) => boolean;
@@ -1356,6 +1520,7 @@ declare class CalendarApp implements ICalendarApp {
1356
1520
  getUseEventDetailDialog: () => boolean;
1357
1521
  getCustomMobileEventRenderer: () => MobileEventRenderer | undefined;
1358
1522
  updateConfig: (config: Partial<CalendarAppConfig>) => void;
1523
+ setOverrides: (overrides: string[]) => void;
1359
1524
  /**
1360
1525
  * Set theme mode
1361
1526
  * @param mode - Theme mode ('light', 'dark', or 'auto')
@@ -1383,7 +1548,7 @@ interface CustomRendering {
1383
1548
  id: string;
1384
1549
  containerEl: HTMLElement;
1385
1550
  generatorName: string;
1386
- generatorArgs: any;
1551
+ generatorArgs: unknown;
1387
1552
  }
1388
1553
  type CustomRenderingListener = (map: Map<string, CustomRendering>) => void;
1389
1554
  declare class CustomRenderingStore {
@@ -1425,7 +1590,7 @@ declare class CalendarRenderer {
1425
1590
  private renderRequested;
1426
1591
  private extraProps;
1427
1592
  constructor(app: ICalendarApp, initialOverrides?: string[]);
1428
- setProps(props: Record<string, any>): void;
1593
+ setProps(props: Record<string, unknown>): void;
1429
1594
  private requestRender;
1430
1595
  /**
1431
1596
  * Mount the calendar to a DOM container.
@@ -1474,6 +1639,12 @@ declare const getStartOfDay: (dateTime: Date | Temporal.PlainDate | Temporal.Pla
1474
1639
  * @returns End of day
1475
1640
  */
1476
1641
  declare const getEndOfDay: (dateTime: Date | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime) => Date | Temporal.ZonedDateTime;
1642
+ /**
1643
+ * Get the ISO week number for a given date
1644
+ * @param date Date object
1645
+ * @returns Week number (1-53)
1646
+ */
1647
+ declare const getWeekNumber: (date: Date) => number;
1477
1648
  /**
1478
1649
  * Check if two dates are on the same day
1479
1650
  * @param date1 Date 1
@@ -1529,18 +1700,29 @@ declare const getLineColor: (calendarIdOrColor: string, registry?: CalendarRegis
1529
1700
  */
1530
1701
  declare const TIME_STEP = 0.25;
1531
1702
  /**
1532
- * Format hours and minutes to HH:MM format
1703
+ * Format hours and minutes to HH:MM format or 12h format (e.g. 1AM)
1533
1704
  * @param hours Hour number (supports decimals, e.g., 14.5 = 14:30)
1534
1705
  * @param minutes Optional minutes (if not provided, extracted from decimal hours)
1535
- * @returns Formatted time string (e.g., "14:30")
1706
+ * @param format Time format ('12h' or '24h', defaults to '24h')
1707
+ * @param showUnits Whether to show AM/PM for 12h format (defaults to true)
1708
+ * @returns Formatted time string (e.g., "14:30" or "2PM")
1709
+ */
1710
+ declare const formatTime: (hours: number, minutes?: number, format?: "12h" | "24h", showUnits?: boolean) => string;
1711
+ /**
1712
+ * Get event end hour (handles cross-day events less than 24 hours)
1713
+ * When an event ends exactly at midnight of the next day and duration is less than 24 hours,
1714
+ * it should be treated as 24:00 of the current day in week/day views to avoid displaying as next day 00:00.
1715
+ * @param event Event object
1716
+ * @returns End hour (0-24)
1536
1717
  */
1537
- declare const formatTime: (hours: number, minutes?: number) => string;
1718
+ declare const getEventEndHour: (event: Event) => number;
1538
1719
  /**
1539
1720
  * Format event time range as a string
1540
1721
  * @param event Event object
1722
+ * @param format Time format ('12h' or '24h', defaults to '24h')
1541
1723
  * @returns Formatted time range (e.g., "14:00 - 16:00" or "All day")
1542
1724
  */
1543
- declare const formatEventTimeRange: (event: Event) => string;
1725
+ declare const formatEventTimeRange: (event: Event, format?: "12h" | "24h") => string;
1544
1726
  /**
1545
1727
  * Round hour to nearest time step
1546
1728
  * @param hour Hour number
@@ -1548,13 +1730,27 @@ declare const formatEventTimeRange: (event: Event) => string;
1548
1730
  */
1549
1731
  declare const roundToTimeStep: (hour: number) => number;
1550
1732
  /**
1551
- * Get event end hour (handles cross-day events less than 24 hours)
1552
- * When an event ends exactly at midnight of the next day and duration is less than 24 hours,
1553
- * it should be treated as 24:00 of the current day in week/day views to avoid displaying as next day 00:00.
1554
- * @param event Event object
1555
- * @returns End hour (0-24)
1733
+ * Generate secondary timezone time labels for each primary time slot.
1734
+ * Uses Temporal to correctly handle DST and timezone conversions.
1735
+ *
1736
+ * @param timeSlots Primary time slots array
1737
+ * @param secondaryTimeZone Secondary IANA timezone identifier
1738
+ * @param timeFormat Time format ('12h' or '24h')
1739
+ * @param referenceDate Reference date used for DST-accurate conversion (defaults to today)
1740
+ * @returns Array of formatted time strings for the secondary timezone
1741
+ */
1742
+ declare const generateSecondaryTimeSlots: (timeSlots: Array<{
1743
+ hour: number;
1744
+ label: string;
1745
+ }>, secondaryTimeZone: TimeZoneValue, timeFormat?: "12h" | "24h", referenceDate?: Date) => string[];
1746
+ /**
1747
+ * Get a short display label for a timezone, e.g. "CST" or "GMT+8".
1748
+ *
1749
+ * @param timeZone IANA timezone identifier
1750
+ * @param date Reference date for DST-aware abbreviation (defaults to today)
1751
+ * @returns Short timezone label
1556
1752
  */
1557
- declare const getEventEndHour: (event: Event) => number;
1753
+ declare const getTimezoneDisplayLabel: (timeZone: TimeZoneValue, date?: Date) => string;
1558
1754
 
1559
1755
  /**
1560
1756
  * Date Constants
@@ -1586,19 +1782,21 @@ declare const shortMonthNames: string[];
1586
1782
  * for week-based operations (Monday-Sunday).
1587
1783
  */
1588
1784
  /**
1589
- * Get the Monday-Sunday range for a given date
1785
+ * Get the week range for a given date
1590
1786
  * @param date Input date
1591
- * @returns Object with monday and sunday dates
1787
+ * @param startOfWeek Week start day (0: Sunday, 1: Monday, etc.)
1788
+ * @returns Object with monday and sunday dates (monday and sunday here are just start/end of week)
1592
1789
  */
1593
- declare const getWeekRange: (date: Date) => {
1790
+ declare const getWeekRange: (date: Date, startOfWeek?: number) => {
1594
1791
  monday: Date;
1595
1792
  sunday: Date;
1596
1793
  };
1597
1794
  /**
1598
- * Get current week dates (Monday-Sunday) with today indicator
1795
+ * Get current week dates with today indicator
1796
+ * @param startOfWeek Week start day (0: Sun, 1: Mon, etc.)
1599
1797
  * @returns Array of 7 date objects with date, month, and isToday flag
1600
1798
  */
1601
- declare const getCurrentWeekDates: () => {
1799
+ declare const getCurrentWeekDates: (startOfWeek?: number) => {
1602
1800
  date: number;
1603
1801
  month: string;
1604
1802
  isToday: boolean;
@@ -1625,6 +1823,16 @@ declare const generateDayData: (date: string | number | Date) => {
1625
1823
  shortMonthName: string;
1626
1824
  isToday: boolean;
1627
1825
  };
1826
+ /**
1827
+ * Determine which month and year a week belongs to (based on majority of days)
1828
+ * @param days Array of day data
1829
+ * @returns Month name, month index, and year
1830
+ */
1831
+ declare const getMonthYearOfWeek: (days: DayData[]) => {
1832
+ month: string;
1833
+ monthIndex: number;
1834
+ year: number;
1835
+ };
1628
1836
  /**
1629
1837
  * Generate week data (7 days starting from given date)
1630
1838
  * @param startDate Week start date
@@ -1647,16 +1855,6 @@ declare const generateWeekData: (startDate: string | number | Date) => {
1647
1855
  year: number;
1648
1856
  };
1649
1857
  };
1650
- /**
1651
- * Determine which month and year a week belongs to (based on majority of days)
1652
- * @param days Array of day data
1653
- * @returns Month name, month index, and year
1654
- */
1655
- declare const getMonthYearOfWeek: (days: DayData[]) => {
1656
- month: string;
1657
- monthIndex: number;
1658
- year: number;
1659
- };
1660
1858
  /**
1661
1859
  * Generate weeks data around a central date
1662
1860
  * @param centralDate Central date for range
@@ -1684,9 +1882,10 @@ declare const generateWeeksData: (centralDate: Date, monthsToLoad?: number) => {
1684
1882
  * Generate week range around a center date
1685
1883
  * @param centerDate Center date for range
1686
1884
  * @param totalWeeks Total number of weeks to generate
1885
+ * @param startOfWeek Week start day (0: Sunday, 1: Monday, etc.)
1687
1886
  * @returns Array of weeks data
1688
1887
  */
1689
- declare function generateWeekRange(centerDate: Date, totalWeeks: number): WeeksData[];
1888
+ declare function generateWeekRange(centerDate: Date, totalWeeks: number, startOfWeek?: number): WeeksData[];
1690
1889
 
1691
1890
  /**
1692
1891
  * Event Utilities
@@ -1786,13 +1985,33 @@ declare const createEventWithRealDate: (eventData: Omit<Event, "start" | "end">,
1786
1985
  * @returns Updated event
1787
1986
  */
1788
1987
  declare const updateEventWithRealDate: (event: Event, newDayIndex: number, weekStart: Date) => Event;
1988
+ /**
1989
+ * Create event with PlainDateTime (default for local events)
1990
+ * This is the recommended function for creating events without timezone complexity
1991
+ */
1992
+ declare const createEventWithPlainDateTime: (eventData: Omit<Event, "start" | "end">, weekStart: Date) => Event;
1993
+ /**
1994
+ * Create event with ZonedDateTime (for timezone-aware events)
1995
+ * Use when explicit timezone control is needed
1996
+ */
1997
+ declare const createEventWithZonedDateTime: (eventData: Omit<Event, "start" | "end">, weekStart: Date, timeZone: string) => Event;
1789
1998
  /**
1790
1999
  * Compare two events for equality
1791
2000
  * @param event1 First event
1792
2001
  * @param event2 Second event
1793
2002
  * @returns Whether events are equal in content
1794
2003
  */
1795
- declare const isEventEqual: (event1: Event | null, event2: Event | null) => boolean;
2004
+ declare const isEventDeepEqual: (event1: Event | null, event2: Event | null) => boolean;
2005
+ /**
2006
+ * Check if event's primary fields (start, end, title) have changed.
2007
+ * This is commonly used to determine if an event update should be persisted
2008
+ * after a drag or resize operation.
2009
+ *
2010
+ * @param oldEvent Original event
2011
+ * @param newEvent Updated event
2012
+ * @returns Whether primary fields have changed
2013
+ */
2014
+ declare const hasEventChanged: (oldEvent: Event, newEvent: Event) => boolean;
1796
2015
 
1797
2016
  /**
1798
2017
  * Test Data Generation Utilities
@@ -1825,7 +2044,7 @@ declare function generateUniKey(): string;
1825
2044
  * Performs a deep comparison between two values to determine if they are equivalent.
1826
2045
  * Supports primitives, Date objects, and plain objects/arrays.
1827
2046
  */
1828
- declare function isDeepEqual(a: any, b: any): boolean;
2047
+ declare function isDeepEqual(a: unknown, b: unknown): boolean;
1829
2048
 
1830
2049
  /**
1831
2050
  * Format date to DD/MM/YYYY format
@@ -1852,15 +2071,15 @@ declare const formatDate: (temporal: Temporal.PlainDate | Temporal.PlainDateTime
1852
2071
  /**
1853
2072
  * Check if temporal is PlainDate (date only, no time)
1854
2073
  */
1855
- declare function isPlainDate(temporal: any): temporal is Temporal.PlainDate;
2074
+ declare function isPlainDate(temporal: unknown): temporal is Temporal.PlainDate;
1856
2075
  /**
1857
2076
  * Check if temporal is PlainDateTime (date + time, no timezone)
1858
2077
  */
1859
- declare function isPlainDateTime(temporal: any): temporal is Temporal.PlainDateTime;
2078
+ declare function isPlainDateTime(temporal: unknown): temporal is Temporal.PlainDateTime;
1860
2079
  /**
1861
2080
  * Check if temporal is ZonedDateTime (date + time + timezone)
1862
2081
  */
1863
- declare function isZonedDateTime(temporal: any): temporal is Temporal.ZonedDateTime;
2082
+ declare function isZonedDateTime(temporal: unknown): temporal is Temporal.ZonedDateTime;
1864
2083
  /**
1865
2084
  * Convert any Temporal type or Date to Date (for internal processing)
1866
2085
  * Handles all three Temporal types and native Date uniformly
@@ -1897,14 +2116,14 @@ declare function extractHourFromTemporal(temporal: Temporal.PlainDate | Temporal
1897
2116
  * @param hour Hour with decimals (e.g., 14.5 = 14:30)
1898
2117
  */
1899
2118
  declare function setHourInTemporal(temporal: Temporal.PlainDateTime | Temporal.ZonedDateTime, hour: number): Temporal.PlainDateTime | Temporal.ZonedDateTime;
1900
- /**
1901
- * Check if two Temporal objects represent the same day
1902
- */
1903
- declare function isSameTemporal(t1: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime | Date, t2: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime | Date): boolean;
1904
2119
  /**
1905
2120
  * Get PlainDate from any Temporal type or Date
1906
2121
  */
1907
2122
  declare function getPlainDate(temporal: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime | Date): Temporal.PlainDate;
2123
+ /**
2124
+ * Check if two Temporal objects represent the same day
2125
+ */
2126
+ declare function isSameTemporal(t1: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime | Date, t2: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime | Date): boolean;
1908
2127
 
1909
2128
  /**
1910
2129
  * Temporal API utility functions
@@ -1914,7 +2133,7 @@ declare function getPlainDate(temporal: Temporal.PlainDate | Temporal.PlainDateT
1914
2133
  /**
1915
2134
  * Check if value is Date object
1916
2135
  */
1917
- declare function isDate(value: any): value is Date;
2136
+ declare function isDate(value: unknown): value is Date;
1918
2137
  /**
1919
2138
  * Convert Temporal.ZonedDateTime to Date
1920
2139
  * @param zdt Temporal.ZonedDateTime
@@ -2125,7 +2344,7 @@ interface CreateEventParams {
2125
2344
  end: Date | Temporal.PlainDate | Temporal.PlainDateTime;
2126
2345
  allDay?: boolean;
2127
2346
  calendarId?: string;
2128
- meta?: Record<string, any>;
2347
+ meta?: Record<string, unknown>;
2129
2348
  }
2130
2349
  /**
2131
2350
  * Timezone event creation parameters
@@ -2139,7 +2358,7 @@ interface CreateTimezoneEventParams {
2139
2358
  end: Date | Temporal.ZonedDateTime;
2140
2359
  timeZone: string;
2141
2360
  calendarId?: string;
2142
- meta?: Record<string, any>;
2361
+ meta?: Record<string, unknown>;
2143
2362
  }
2144
2363
  /**
2145
2364
  * Create local event (recommended for most use cases)
@@ -2234,7 +2453,7 @@ declare function createTimedEvent(id: string, title: string, start: Date, end: D
2234
2453
  declare function convertDateEvent(id: string, title: string, startDate: Date, endDate: Date, allDay?: boolean, options?: {
2235
2454
  description?: string;
2236
2455
  calendarId?: string;
2237
- meta?: Record<string, any>;
2456
+ meta?: Record<string, unknown>;
2238
2457
  }): Event;
2239
2458
  /**
2240
2459
  * Convert legacy Date-based event to timezone-aware event
@@ -2243,12 +2462,12 @@ declare function convertDateEvent(id: string, title: string, startDate: Date, en
2243
2462
  declare function convertDateEventWithTimeZone(id: string, title: string, startDate: Date, endDate: Date, timeZone: string, options?: {
2244
2463
  description?: string;
2245
2464
  calendarId?: string;
2246
- meta?: Record<string, any>;
2465
+ meta?: Record<string, unknown>;
2247
2466
  }): Event;
2248
2467
 
2249
2468
  type CalendarSearchEvent = Event & {
2250
2469
  color?: string;
2251
- [key: string]: any;
2470
+ [key: string]: unknown;
2252
2471
  };
2253
2472
 
2254
2473
  /**
@@ -2256,7 +2475,7 @@ type CalendarSearchEvent = Event & {
2256
2475
  * @param dateInput Date, string, or Temporal object
2257
2476
  * @returns Date object
2258
2477
  */
2259
- declare const getDateObj: (dateInput: any) => Date;
2478
+ declare const getDateObj: (dateInput: unknown) => Date;
2260
2479
  /**
2261
2480
  * Helper to normalize date (reset time to 00:00:00)
2262
2481
  * @param date Date object
@@ -2271,7 +2490,7 @@ declare const normalizeDate: (date: Date) => Date;
2271
2490
  * @param t Translation function
2272
2491
  * @returns Object with title and colorClass
2273
2492
  */
2274
- declare const getSearchHeaderInfo: (groupDate: Date, today: Date, locale: string, t: (key: any) => string) => {
2493
+ declare const getSearchHeaderInfo: (groupDate: Date, today: Date, locale: string, t: (key: TranslationKey) => string) => {
2275
2494
  title: string;
2276
2495
  colorClass: string;
2277
2496
  };
@@ -2388,17 +2607,9 @@ interface ICSParseError {
2388
2607
  }
2389
2608
 
2390
2609
  /**
2391
- * ICS Date Utilities
2392
- *
2393
- * Convert between ICS date formats (RFC 5545) and Temporal API types.
2394
- *
2395
- * ICS Date Formats:
2396
- * 1. DATE (all-day): YYYYMMDD (e.g., 20250115)
2397
- * 2. DATE-TIME (local): YYYYMMDDTHHMMSS (e.g., 20250115T143000)
2398
- * 3. DATE-TIME (UTC): YYYYMMDDTHHMMSSZ (e.g., 20250115T143000Z)
2399
- * 4. DATE-TIME (with TZID): DTSTART;TZID=America/New_York:20250115T143000
2610
+ * Pad number to 2 digits
2400
2611
  */
2401
-
2612
+ declare function pad2(num: number | string): string;
2402
2613
  /**
2403
2614
  * Parse ICS date string to Temporal type
2404
2615
  *
@@ -2423,6 +2634,14 @@ declare function formatICSDate(temporal: Temporal.PlainDate | Temporal.PlainDate
2423
2634
  * Format a Date to ICS timestamp (UTC format for DTSTAMP)
2424
2635
  */
2425
2636
  declare function formatDateToICSTimestamp(date: Date): string;
2637
+ declare function escapeICSValue(value: string): string;
2638
+ declare function unescapeICSValue(value: string): string;
2639
+ declare function foldLine(line: string): string;
2640
+ declare function formatProperty(name: string, value: string, params?: Record<string, string>): string;
2641
+ declare function generateVEvent(event: Event): string[];
2642
+ declare function extractVEvents(lines: string[]): string[][];
2643
+ declare function parseVEventLines(lines: string[]): ICSVEvent;
2644
+ declare function convertToDayFlowEvent(icsEvent: ICSVEvent, options: ICSImportOptions): Event;
2426
2645
 
2427
2646
  /**
2428
2647
  * ICS Parser
@@ -2494,9 +2713,9 @@ declare function getIntlLabel(key: 'today' | 'day' | 'week' | 'month' | 'year',
2494
2713
  */
2495
2714
  declare function capitalize(str: string): string;
2496
2715
  /**
2497
- * Get localized weekday labels (Mon, Tue, etc.)
2716
+ * Get localized weekday labels starting from startOfWeek (0: Sun, 1: Mon, etc.)
2498
2717
  */
2499
- declare const getWeekDaysLabels: (locale: string, format?: "long" | "short" | "narrow") => string[];
2718
+ declare const getWeekDaysLabels: (locale: string, format?: "long" | "short" | "narrow", startOfWeek?: number) => string[];
2500
2719
  /**
2501
2720
  * Get localized month labels
2502
2721
  */
@@ -2531,7 +2750,7 @@ declare function isValidLocale(locale: string): boolean;
2531
2750
  interface LocaleContextValue {
2532
2751
  locale: LocaleCode;
2533
2752
  t: (key: TranslationKey, vars?: Record<string, string>) => string;
2534
- getWeekDaysLabels: (locale: string, format?: 'long' | 'short' | 'narrow') => string[];
2753
+ getWeekDaysLabels: (locale: string, format?: 'long' | 'short' | 'narrow', startOfWeek?: number) => string[];
2535
2754
  getMonthLabels: (locale: string, format?: 'long' | 'short' | 'narrow' | 'numeric' | '2-digit') => string[];
2536
2755
  isDefault?: boolean;
2537
2756
  }
@@ -2545,7 +2764,7 @@ declare function useLocale(): LocaleContextValue;
2545
2764
  interface LocaleProviderProps {
2546
2765
  locale?: LocaleCode | Locale;
2547
2766
  messages?: LocaleMessages;
2548
- children?: any;
2767
+ children?: ComponentChildren;
2549
2768
  }
2550
2769
  declare const LocaleProvider: ({ locale, messages, children, }: LocaleProviderProps) => preact.JSX.Element;
2551
2770
 
@@ -2587,7 +2806,7 @@ interface ContextMenuProps {
2587
2806
  x: number;
2588
2807
  y: number;
2589
2808
  onClose: () => void;
2590
- children: any;
2809
+ children: ComponentChildren;
2591
2810
  className?: string;
2592
2811
  }
2593
2812
  declare const ContextMenu: preact.FunctionalComponent<preact_compat.PropsWithoutRef<ContextMenuProps> & {
@@ -2595,18 +2814,20 @@ declare const ContextMenu: preact.FunctionalComponent<preact_compat.PropsWithout
2595
2814
  }>;
2596
2815
  declare const ContextMenuItem: ({ onClick, children, icon, danger, disabled, }: {
2597
2816
  onClick: () => void;
2598
- children: any;
2599
- icon?: any;
2817
+ children: ComponentChildren;
2818
+ icon?: ComponentChildren;
2600
2819
  danger?: boolean;
2601
2820
  disabled?: boolean;
2602
- }) => h.JSX.Element;
2603
- declare const ContextMenuSeparator: () => h.JSX.Element;
2604
- declare const ContextMenuLabel: any;
2821
+ }) => preact.JSX.Element;
2822
+ declare const ContextMenuSeparator: () => preact.JSX.Element;
2823
+ declare const ContextMenuLabel: ({ children, }: {
2824
+ children: ComponentChildren;
2825
+ }) => preact.JSX.Element;
2605
2826
  declare const ContextMenuColorPicker: ({ selectedColor, onSelect, onCustomColor, }: {
2606
2827
  selectedColor?: string;
2607
2828
  onSelect: (color: string) => void;
2608
2829
  onCustomColor?: () => void;
2609
- }) => h.JSX.Element;
2830
+ }) => preact.JSX.Element;
2610
2831
 
2611
2832
  interface BlossomColorPickerProps extends Partial<BlossomColorPickerOptions> {
2612
2833
  className?: string;
@@ -2619,7 +2840,7 @@ interface DefaultColorPickerProps {
2619
2840
  hex: string;
2620
2841
  }, isPending?: boolean) => void;
2621
2842
  onClose?: () => void;
2622
- [key: string]: any;
2843
+ [key: string]: unknown;
2623
2844
  }
2624
2845
  declare const DefaultColorPicker: ({ color, onChange, onClose, }: DefaultColorPickerProps) => preact.JSX.Element;
2625
2846
 
@@ -2633,13 +2854,13 @@ interface MiniCalendarProps {
2633
2854
  }
2634
2855
  declare const MiniCalendar: ({ visibleMonth, currentDate, showHeader, onMonthChange, onDateSelect, }: MiniCalendarProps) => preact.JSX.Element;
2635
2856
 
2636
- declare const CreateCalendarDialog: ({ onClose, onCreate, colorPickerMode, }: CreateCalendarDialogProps) => preact.VNode<any> | null;
2857
+ declare const CreateCalendarDialog: ({ onClose, onCreate, app, }: CreateCalendarDialogProps) => preact.VNode<any> | null;
2637
2858
 
2638
2859
  interface ContentSlotProps {
2639
- generatorName: string;
2640
- generatorArgs?: any;
2641
- defaultContent?: any;
2642
- store?: any;
2860
+ generatorName: string | null;
2861
+ generatorArgs?: unknown;
2862
+ defaultContent?: ComponentChildren;
2863
+ store?: CustomRenderingStore | null;
2643
2864
  }
2644
2865
  /**
2645
2866
  * Preact component: Creates a placeholder <div> and registers it with CustomRenderingStore.
@@ -2685,5 +2906,5 @@ declare const sidebarHeaderToggle = "df-sidebar-header-toggle flex h-8 w-8 items
2685
2906
  */
2686
2907
  declare const sidebarHeaderTitle = "df-sidebar-header-title text-sm font-semibold text-gray-700 dark:text-gray-200";
2687
2908
 
2688
- export { BlossomColorPicker, CalendarApp, CalendarRegistry, CalendarRenderer, Check, ChevronRight, ChevronsUpDown, ContentSlot, ContextMenu, ContextMenuColorPicker, ContextMenuItem, ContextMenuLabel, ContextMenuSeparator, CreateCalendarDialog, CustomRenderingStore, DefaultColorPicker, LAYOUT_CONFIG, LOCALES, LocaleContext, LocaleProvider, MiniCalendar, PanelRightClose, PanelRightOpen, Plus, TIME_STEP, VIRTUAL_MONTH_SCROLL_CONFIG, ViewType, WeekDataCache, addDays, buildParseRegExp, calculateDayIndex, calendarPickerDropdown, cancelButton, capitalize, clipboardStore, conditionalTheme, convertDateEvent, convertDateEventWithTimeZone, createAllDayEvent, createDateWithHour, createDayView, createEvent, createEventWithDate, createEventWithRealDate, createEvents, createEventsPlugin, createMonthView, createStandardViews, createTemporalWithHour, createTimedEvent, createTimezoneEvent, createTimezoneEvents, createWeekView, createYearView, dateToPlainDate, dateToPlainDateTime, dateToZonedDateTime, daysBetween, daysDifference, downloadICS, en, extractHourFromDate, extractHourFromTemporal, formatDate, formatDateConsistent, formatDateToICSTimestamp, formatEventTimeRange, formatICSDate, formatMonthYear, formatTemporal, formatTime, generateDayData, generateICS, generateUniKey, generateWeekData, generateWeekRange, generateWeeksData, getAllDayEventsForDay, getCalendarColorsForHex, getCurrentWeekDates, getDateByDayIndex, getDateObj, getDayIndexByDate, getEndOfDay, getEndOfTemporal, getEventBgColor, getEventEndHour, getEventTextColor, getEventsForDay, getEventsForWeek, getIntlLabel, getLineColor, getMonthLabels, getMonthYearOfWeek, getPlainDate, getSearchHeaderInfo, getSelectedBgColor, getStartOfDay, getStartOfTemporal, getTestEvents, getWeekDaysLabels, getWeekRange, getZoneId, groupSearchResults, importICSFile, isDate, isDeepEqual, isEventEqual, isEventInWeek, isMultiDayEvent, isMultiDayTemporalEvent, isPlainDate, isPlainDateTime, isSameDay, isSamePlainDate, isSameTemporal, isValidLocale, isZonedDateTime, mergeClasses, mergeFormatTemplate, monthNames, normalizeCssWidth, normalizeDate, normalizeLocale, normalizeToZoned, now, pad, parseICS, parseICSDate, parseTemporalString, plainDateTimeToDate, plainDateToDate, recalculateEventDays, registerDragImplementation, registerLocale, registerSidebarImplementation, resolveAppliedTheme, roundToTimeStep, scrollbarTakesSpace, setHourInTemporal, shortMonthNames, sidebarContainer, sidebarHeader, sidebarHeaderTitle, sidebarHeaderToggle, t, temporalToDate, themeClasses, themeCn, today, updateEventDateAndDay, updateEventWithRealDate, useDragForView, useLocale, useSidebarBridge, weekDays, weekDaysFullName, zonedDateTimeToDate };
2689
- export type { BalanceStrategy, BaseViewProps, CalendarAppConfig, CalendarAppState, CalendarCallbacks, CalendarColors, CalendarConfig, CalendarHeaderProps, CalendarPlugin, CalendarType, CalendarView, CalendarsConfig, CreateCalendarDialogProps, CreateEventParams, CreateTimezoneEventParams, CustomRendering, DayData, DayViewConfig, DayViewProps, DragConfig, DragHookOptions, DragHookReturn, DragIndicatorProps, DragIndicatorRenderer, DragIntegrationProps, DragPluginConfig, DragRef, DragService, Event, EventChange, EventDetailContentProps, EventDetailContentRenderer, EventDetailDialogProps, EventDetailDialogRenderer, EventDetailPanelProps, EventDetailPanelRenderer, EventDetailPosition, EventGroup, EventLayout, EventRelations, EventsPluginConfig, EventsService, ICSDateParams, ICSExportOptions, ICSImportOptions, ICSImportResult, ICSParseError, ICSVEvent, ICalendarApp, Locale, LocaleCode, LocaleContextValue, LocaleDict, LocaleMessages, LocaleProviderProps, MobileEventProps, MobileEventRenderer, Mode, MonthDragState, MonthEventDragState, MonthViewConfig, MonthViewProps, NestedLayer, RangeChangeReason, ReadOnlyConfig, SidebarBridgeReturn, SpecialLayoutRule, SubtreeAnalysis, SupportedLang, TComponent, TNode, ThemeColors, ThemeConfig, ThemeMode, TransferOperation, TranslationKey, UnifiedDragRef, UseCalendarAppReturn, UseCalendarReturn, UseDragCommonReturn, UseDragHandlersParams, UseDragHandlersReturn, UseDragManagerReturn, UseDragStateReturn, UseMonthDragParams, UseMonthDragReturn, UseVirtualMonthScrollProps, UseVirtualMonthScrollReturn, UseVirtualScrollProps, UseVirtualScrollReturn, UseWeekDayDragParams, UseWeekDayDragReturn, ViewAdapterProps, ViewFactory, ViewFactoryConfig, VirtualItem, VirtualScrollIntegrationProps, VirtualWeekItem, WeekDayDragState, WeekViewConfig, WeekViewProps, WeeksData, YearViewConfig, YearViewProps, useDragProps, useDragReturn };
2909
+ export { BlossomColorPicker, CalendarApp, CalendarRegistry, CalendarRenderer, Check, ChevronRight, ChevronsUpDown, ContentSlot, ContextMenu, ContextMenuColorPicker, ContextMenuItem, ContextMenuLabel, ContextMenuSeparator, CreateCalendarDialog, CustomRenderingStore, DefaultColorPicker, LAYOUT_CONFIG, LOCALES, LocaleContext, LocaleProvider, MiniCalendar, PanelRightClose, PanelRightOpen, Plus, TIME_STEP, TimeZone, VIRTUAL_MONTH_SCROLL_CONFIG, ViewType, WeekDataCache, addDays, buildParseRegExp, calculateDayIndex, calendarPickerDropdown, cancelButton, capitalize, clipboardStore, conditionalTheme, convertDateEvent, convertDateEventWithTimeZone, convertToDayFlowEvent, createAllDayEvent, createDateWithHour, createDayView, createEvent, createEventWithDate, createEventWithPlainDateTime, createEventWithRealDate, createEventWithZonedDateTime, createEvents, createEventsPlugin, createMonthView, createStandardViews, createTemporalWithHour, createTimedEvent, createTimezoneEvent, createTimezoneEvents, createWeekView, createYearView, dateToPlainDate, dateToPlainDateTime, dateToZonedDateTime, daysBetween, daysDifference, downloadICS, en, escapeICSValue, extractHourFromDate, extractHourFromTemporal, extractVEvents, foldLine, formatDate, formatDateConsistent, formatDateToICSTimestamp, formatEventTimeRange, formatICSDate, formatMonthYear, formatProperty, formatTemporal, formatTime, generateDayData, generateICS, generateSecondaryTimeSlots, generateUniKey, generateVEvent, generateWeekData, generateWeekRange, generateWeeksData, getAllDayEventsForDay, getCalendarColorsForHex, getCurrentWeekDates, getDateByDayIndex, getDateObj, getDayIndexByDate, getEndOfDay, getEndOfTemporal, getEventBgColor, getEventEndHour, getEventTextColor, getEventsForDay, getEventsForWeek, getIntlLabel, getLineColor, getMonthLabels, getMonthYearOfWeek, getPlainDate, getSearchHeaderInfo, getSelectedBgColor, getStartOfDay, getStartOfTemporal, getTestEvents, getTimezoneDisplayLabel, getWeekDaysLabels, getWeekNumber, getWeekRange, getZoneId, groupSearchResults, hasEventChanged, importICSFile, isDate, isDeepEqual, isEventDeepEqual, isEventInWeek, isMultiDayEvent, isMultiDayTemporalEvent, isPlainDate, isPlainDateTime, isSameDay, isSamePlainDate, isSameTemporal, isValidLocale, isZonedDateTime, mergeClasses, mergeFormatTemplate, monthNames, normalizeCssWidth, normalizeDate, normalizeLocale, normalizeToZoned, now, pad, pad2, parseICS, parseICSDate, parseTemporalString, parseVEventLines, plainDateTimeToDate, plainDateToDate, recalculateEventDays, registerDragImplementation, registerLocale, registerSidebarImplementation, resolveAppliedTheme, roundToTimeStep, scrollbarTakesSpace, setHourInTemporal, shortMonthNames, sidebarContainer, sidebarHeader, sidebarHeaderTitle, sidebarHeaderToggle, t, temporalToDate, themeClasses, themeCn, today, unescapeICSValue, updateEventDateAndDay, updateEventWithRealDate, useDragForView, useLocale, useSidebarBridge, weekDays, weekDaysFullName, zonedDateTimeToDate };
2910
+ export type { BalanceStrategy, BaseViewProps, CalendarAppConfig, CalendarAppState, CalendarCallbacks, CalendarColors, CalendarConfig, CalendarHeaderProps, CalendarPlugin, CalendarType, CalendarView, CalendarsConfig, ColorPickerProps, CreateCalendarDialogColorPickerProps, CreateCalendarDialogProps, CreateEventParams, CreateTimezoneEventParams, CustomRendering, DayData, DayViewConfig, DayViewProps, DragConfig, DragHookOptions, DragHookReturn, DragIndicatorProps, DragIndicatorRenderer, DragIntegrationProps, DragPluginConfig, DragRef, DragService, Event, EventChange, EventContentSlotArgs, EventDetailContentProps, EventDetailContentRenderer, EventDetailDialogProps, EventDetailDialogRenderer, EventDetailPanelProps, EventDetailPanelRenderer, EventDetailPosition, EventGroup, EventLayout, EventRelations, EventsPluginConfig, EventsService, ICSDateParams, ICSExportOptions, ICSImportOptions, ICSImportResult, ICSParseError, ICSVEvent, ICalendarApp, Locale, LocaleCode, LocaleContextValue, LocaleDict, LocaleMessages, LocaleProviderProps, MobileEventProps, MobileEventRenderer, Mode, MonthDragState, MonthEventDragState, MonthViewConfig, MonthViewProps, NestedLayer, RangeChangeReason, ReadOnlyConfig, SidebarBridgeReturn, SpecialLayoutRule, SubtreeAnalysis, SupportedLang, TComponent, TNode, ThemeColors, ThemeConfig, ThemeMode, TimeZoneValue, TitleBarSlotProps, TransferOperation, TranslationKey, UnifiedDragRef, UseCalendarAppReturn, UseCalendarReturn, UseDragCommonReturn, UseDragHandlersParams, UseDragHandlersReturn, UseDragManagerReturn, UseDragStateReturn, UseMonthDragParams, UseMonthDragReturn, UseVirtualMonthScrollProps, UseVirtualMonthScrollReturn, UseVirtualScrollProps, UseVirtualScrollReturn, UseWeekDayDragParams, UseWeekDayDragReturn, ViewAdapterProps, ViewFactory, ViewFactoryConfig, VirtualItem, VirtualScrollIntegrationProps, VirtualWeekItem, WeekDayDragState, WeekViewConfig, WeekViewProps, WeeksData, YearViewConfig, YearViewProps, useDragProps, useDragReturn };