@dayflow/core 3.3.6 → 3.4.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 DayFlow Contributors
+Copyright (c) 2025 Jayce Li
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/index.d.ts

@@ -41,8 +41,8 @@ interface CalendarType {
     isDefault?: boolean;
     /** Whether events of this type should be visible */
     isVisible?: boolean;
-    /** Whether this calendar was created by subscribing to a remote ICS URL */
-    subscribed?: boolean;
+    /** Whether this calendar is read-only (disables UI mutations like drag/edit) */
+    readOnly?: boolean;
     /** The source of this calendar (e.g., 'Google Calendar', 'iCloud', 'Outlook') */
     source?: string;
     /** Subscription status and metadata */
@@ -330,6 +330,129 @@ interface SpecialLayoutRule {
     reason?: string;
 }
 
+/**
+ * Common IANA TimeZone identifiers.
+ * This enum provides a convenient way for users to specify secondary timezones
+ * without having to look up the exact Temporal/Intl TimeZone strings.
+ */
+declare enum TimeZone {
+    UTC = "UTC",
+    NEW_YORK = "America/New_York",
+    CHICAGO = "America/Chicago",
+    DENVER = "America/Denver",
+    LOS_ANGELES = "America/Los_Angeles",
+    TORONTO = "America/Toronto",
+    VANCOUVER = "America/Vancouver",
+    PHOENIX = "America/Phoenix",
+    ANCHORAGE = "America/Anchorage",
+    HONOLULU = "Pacific/Honolulu",
+    MEXICO_CITY = "America/Mexico_City",
+    WINNIPEG = "America/Winnipeg",
+    HALIFAX = "America/Halifax",
+    ST_JOHNS = "America/St_Johns",
+    DETROIT = "America/Detroit",
+    LONDON = "Europe/London",
+    PARIS = "Europe/Paris",
+    BERLIN = "Europe/Berlin",
+    MADRID = "Europe/Madrid",
+    ROME = "Europe/Rome",
+    AMSTERDAM = "Europe/Amsterdam",
+    ZURICH = "Europe/Zurich",
+    STOCKHOLM = "Europe/Stockholm",
+    OSLO = "Europe/Oslo",
+    COPENHAGEN = "Europe/Copenhagen",
+    MOSCOW = "Europe/Moscow",
+    ISTANBUL = "Europe/Istanbul",
+    DUBLIN = "Europe/Dublin",
+    LISBON = "Europe/Lisbon",
+    PRAGUE = "Europe/Prague",
+    VIENNA = "Europe/Vienna",
+    WARSAW = "Europe/Warsaw",
+    BRUSSELS = "Europe/Brussels",
+    ATHENS = "Europe/Athens",
+    BUCHAREST = "Europe/Bucharest",
+    HELSINKI = "Europe/Helsinki",
+    KYIV = "Europe/Kyiv",
+    BUDAPEST = "Europe/Budapest",
+    BELGRADE = "Europe/Belgrade",
+    LUXEMBOURG = "Europe/Luxembourg",
+    MONACO = "Europe/Monaco",
+    REYKJAVIK = "Atlantic/Reykjavik",
+    TOKYO = "Asia/Tokyo",
+    SHANGHAI = "Asia/Shanghai",
+    HONG_KONG = "Asia/Hong_Kong",
+    TAIPEI = "Asia/Taipei",
+    SEOUL = "Asia/Seoul",
+    SINGAPORE = "Asia/Singapore",
+    HANOI = "Asia/Ho_Chi_Minh",
+    BANGKOK = "Asia/Bangkok",
+    JAKARTA = "Asia/Jakarta",
+    KUALA_LUMPUR = "Asia/Kuala_Lumpur",
+    MANILA = "Asia/Manila",
+    DUBAI = "Asia/Dubai",
+    KOLKATA = "Asia/Kolkata",
+    RIYADH = "Asia/Riyadh",
+    TEHRAN = "Asia/Tehran",
+    JERUSALEM = "Asia/Jerusalem",
+    TEL_AVIV = "Asia/Tel_Aviv",
+    BAGHDAD = "Asia/Baghdad",
+    DHAKA = "Asia/Dhaka",
+    KARACHI = "Asia/Karachi",
+    KABUL = "Asia/Kabul",
+    KATHMANDU = "Asia/Kathmandu",
+    COLOMBO = "Asia/Colombo",
+    TASHKENT = "Asia/Tashkent",
+    ALMATY = "Asia/Almaty",
+    PHNOM_PENH = "Asia/Phnom_Penh",
+    VIENTIANE = "Asia/Vientiane",
+    MUSCAT = "Asia/Muscat",
+    SYDNEY = "Australia/Sydney",
+    MELBOURNE = "Australia/Melbourne",
+    BRISBANE = "Australia/Brisbane",
+    PERTH = "Australia/Perth",
+    ADELAIDE = "Australia/Adelaide",
+    DARWIN = "Australia/Darwin",
+    HOBART = "Australia/Hobart",
+    AUCKLAND = "Pacific/Auckland",
+    FIJI = "Pacific/Fiji",
+    GUAM = "Pacific/Guam",
+    NOUMEA = "Pacific/Noumea",
+    PAGO_PAGO = "Pacific/Pago_Pago",
+    PORT_MORESBY = "Pacific/Port_Moresby",
+    SAO_PAULO = "America/Sao_Paulo",
+    BUENOS_AIRES = "America/Argentina/Buenos_Aires",
+    SANTIAGO = "America/Santiago",
+    LIMA = "America/Lima",
+    BOGOTA = "America/Bogota",
+    CARACAS = "America/Caracas",
+    LA_PAZ = "America/La_Paz",
+    MONTEVIDEO = "America/Montevideo",
+    QUITO = "America/Quito",
+    ASUNCION = "America/Asuncion",
+    GEORGETOWN = "America/Guyana",
+    CAIRO = "Africa/Cairo",
+    JOHANNESBURG = "Africa/Johannesburg",
+    LAGOS = "Africa/Lagos",
+    NAIROBI = "Africa/Nairobi",
+    CASABLANCA = "Africa/Casablanca",
+    ALGIERS = "Africa/Algiers",
+    TUNIS = "Africa/Tunis",
+    ADDIS_ABABA = "Africa/Addis_Ababa",
+    ACCRA = "Africa/Accra",
+    DAKAR = "Africa/Dakar",
+    LUANDA = "Africa/Luanda",
+    ANTANANARIVO = "Indian/Antananarivo",
+    KINSHASA = "Africa/Kinshasa",
+    DAR_ES_SALAAM = "Africa/Dar_es_Salaam",
+    MCMURDO = "Antarctica/McMurdo",
+    CASEY = "Antarctica/Casey"
+}
+/**
+ * Type helper for secondaryTimeZone configuration
+ * Allows using either the TimeZone enum or a raw IANA string.
+ */
+type TimeZoneValue = TimeZone | string;
+
 /** Generic type for framework-specific components */
 type TComponent = AnyComponent<any, any>;
 /** Generic type for framework-specific nodes/elements */
@@ -356,7 +479,7 @@ type CalendarViewType = ViewType | string;
 interface CalendarPlugin {
     name: string;
     install: (app: ICalendarApp) => void;
-    config?: Record<string, unknown>;
+    config?: any;
     api?: unknown;
 }
 /**
@@ -450,12 +573,19 @@ interface CalendarAppConfig {
     defaultCalendar?: string;
     theme?: ThemeConfig;
     useEventDetailDialog?: boolean;
-    useCalendarHeader?: boolean | ((props: CalendarHeaderProps) => TNode);
+    useCalendarHeader?: boolean;
     customMobileEventRenderer?: MobileEventRenderer;
     locale?: string | Locale;
     readOnly?: boolean | ReadOnlyConfig;
     /** Custom sort comparator for all-day events, applied in day/week/month/year views. */
     allDaySortComparator?: AllDaySortComparator;
+    /**
+     * Global display and editing timezone for all views.
+     * Controls how event times are projected and how drag/resize/create operations interpret wall-clock time.
+     * Defaults to the user's system timezone.
+     * Switching this field only triggers a re-render — it never calls onEventUpdate or any persistence callback.
+     */
+    timeZone?: TimeZoneValue;
 }
 /**
  * Read-only configuration
@@ -481,6 +611,8 @@ interface CalendarAppState {
     readOnly: boolean | ReadOnlyConfig;
     overrides: string[];
     allDaySortComparator?: AllDaySortComparator;
+    /** Resolved global timezone (IANA string). See CalendarAppConfig.timeZone. */
+    timeZone: string;
 }
 /**
  * Calendar application instance
@@ -488,8 +620,8 @@ interface CalendarAppState {
  */
 interface ICalendarApp {
     state: CalendarAppState;
-    getReadOnlyConfig: () => ReadOnlyConfig;
-    canMutateFromUI: () => boolean;
+    getReadOnlyConfig: (id?: string) => ReadOnlyConfig;
+    canMutateFromUI: (id?: string) => boolean;
     subscribe: (listener: (app: ICalendarApp) => void) => () => void;
     changeView: (view: CalendarViewType) => void;
     getCurrentView: () => CalendarView;
@@ -534,12 +666,14 @@ interface ICalendarApp {
     dismissUI: () => void;
     getPlugin: <T = unknown>(name: string) => T | undefined;
     hasPlugin: (name: string) => boolean;
-    getCalendarHeaderConfig: () => boolean | ((props: CalendarHeaderProps) => TNode);
+    getCalendarHeaderConfig: () => boolean;
     triggerRender: () => void;
     getCalendarRegistry: () => CalendarRegistry;
     getUseEventDetailDialog: () => boolean;
     getCustomMobileEventRenderer: () => MobileEventRenderer | undefined;
     updateConfig: (config: Partial<CalendarAppConfig>) => void;
+    /** The resolved global display/edit timezone (IANA string). */
+    readonly timeZone: string;
     setOverrides: (overrides: string[]) => void;
     setTheme: (mode: ThemeMode) => void;
     getTheme: () => ThemeMode;
@@ -583,7 +717,7 @@ interface UseCalendarAppReturn {
     setVisibleMonth: (date: Date) => void;
     getVisibleMonth: () => Date;
     emitVisibleRange: (start: Date, end: Date, reason?: RangeChangeReason) => void;
-    canMutateFromUI: () => boolean;
+    canMutateFromUI: (id?: string) => boolean;
     readOnlyConfig: ReadOnlyConfig;
 }
 /**
@@ -1018,139 +1152,6 @@ interface EventDetailDialogProps {
  */
 type EventDetailDialogRenderer = AnyComponent<EventDetailDialogProps, any>;
 
-/**
- * Common IANA TimeZone identifiers.
- * This enum provides a convenient way for users to specify secondary timezones
- * without having to look up the exact Temporal/Intl TimeZone strings.
- */
-declare enum TimeZone {
-    UTC = "UTC",
-    NEW_YORK = "America/New_York",
-    CHICAGO = "America/Chicago",
-    DENVER = "America/Denver",
-    LOS_ANGELES = "America/Los_Angeles",
-    TORONTO = "America/Toronto",
-    VANCOUVER = "America/Vancouver",
-    PHOENIX = "America/Phoenix",
-    ANCHORAGE = "America/Anchorage",
-    HONOLULU = "Pacific/Honolulu",
-    MEXICO_CITY = "America/Mexico_City",
-    WINNIPEG = "America/Winnipeg",
-    HALIFAX = "America/Halifax",
-    ST_JOHNS = "America/St_Johns",
-    DETROIT = "America/Detroit",
-    MIAMI = "America/Miami",
-    SEATTLE = "America/Los_Angeles",
-    ATLANTA = "America/New_York",
-    DALLAS = "America/Chicago",
-    HOUSTON = "America/Chicago",
-    LAS_VEGAS = "America/Los_Angeles",
-    SAN_FRANCISCO = "America/Los_Angeles",
-    LONDON = "Europe/London",
-    PARIS = "Europe/Paris",
-    BERLIN = "Europe/Berlin",
-    MADRID = "Europe/Madrid",
-    ROME = "Europe/Rome",
-    AMSTERDAM = "Europe/Amsterdam",
-    ZURICH = "Europe/Zurich",
-    STOCKHOLM = "Europe/Stockholm",
-    OSLO = "Europe/Oslo",
-    COPENHAGEN = "Europe/Copenhagen",
-    MOSCOW = "Europe/Moscow",
-    ISTANBUL = "Europe/Istanbul",
-    DUBLIN = "Europe/Dublin",
-    LISBON = "Europe/Lisbon",
-    PRAGUE = "Europe/Prague",
-    VIENNA = "Europe/Vienna",
-    WARSAW = "Europe/Warsaw",
-    BRUSSELS = "Europe/Brussels",
-    ATHENS = "Europe/Athens",
-    BUCHAREST = "Europe/Bucharest",
-    HELSINKI = "Europe/Helsinki",
-    KYIV = "Europe/Kyiv",
-    BUDAPEST = "Europe/Budapest",
-    BELGRADE = "Europe/Belgrade",
-    LUXEMBOURG = "Europe/Luxembourg",
-    MONACO = "Europe/Monaco",
-    REYKJAVIK = "Atlantic/Reykjavik",
-    TOKYO = "Asia/Tokyo",
-    SHANGHAI = "Asia/Shanghai",
-    BEIJING = "Asia/Shanghai",
-    HONG_KONG = "Asia/Hong_Kong",
-    TAIPEI = "Asia/Taipei",
-    SEOUL = "Asia/Seoul",
-    SINGAPORE = "Asia/Singapore",
-    HANOI = "Asia/Ho_Chi_Minh",
-    BANGKOK = "Asia/Bangkok",
-    JAKARTA = "Asia/Jakarta",
-    KUALA_LUMPUR = "Asia/Kuala_Lumpur",
-    MANILA = "Asia/Manila",
-    DUBAI = "Asia/Dubai",
-    KOLKATA = "Asia/Kolkata",
-    MUMBAI = "Asia/Kolkata",
-    RIYADH = "Asia/Riyadh",
-    TEHRAN = "Asia/Tehran",
-    JERUSALEM = "Asia/Jerusalem",
-    TEL_AVIV = "Asia/Tel_Aviv",
-    BAGHDAD = "Asia/Baghdad",
-    DHAKA = "Asia/Dhaka",
-    KARA_CHI = "Asia/Karachi",
-    KABUL = "Asia/Kabul",
-    KATHMANDU = "Asia/Kathmandu",
-    COLOMBO = "Asia/Colombo",
-    TASHKENT = "Asia/Tashkent",
-    ALMATY = "Asia/Almaty",
-    PHNOM_PENH = "Asia/Phnom_Penh",
-    VIENTIANE = "Asia/Vientiane",
-    MUSCAT = "Asia/Muscat",
-    SYDNEY = "Australia/Sydney",
-    MELBOURNE = "Australia/Melbourne",
-    BRISBANE = "Australia/Brisbane",
-    PERTH = "Australia/Perth",
-    ADELAIDE = "Australia/Adelaide",
-    DARWIN = "Australia/Darwin",
-    HOBART = "Australia/Hobart",
-    AUCKLAND = "Pacific/Auckland",
-    FIJI = "Pacific/Fiji",
-    GUAM = "Pacific/Guam",
-    NOUMEA = "Pacific/Noumea",
-    PAGO_PAGO = "Pacific/Pago_Pago",
-    PORT_MORESBY = "Pacific/Port_Moresby",
-    SAO_PAULO = "America/Sao_Paulo",
-    RIO_DE_JANEIRO = "America/Sao_Paulo",
-    BUENOS_AIRES = "America/Argentina/Buenos_Aires",
-    SANTIAGO = "America/Santiago",
-    LIMA = "America/Lima",
-    BOGOTA = "America/Bogota",
-    CARACAS = "America/Caracas",
-    LA_PAZ = "America/La_Paz",
-    MONTEVIDEO = "America/Montevideo",
-    QUITO = "America/Quito",
-    ASUNCION = "America/Asuncion",
-    GEORGETOWN = "America/Guyana",
-    CAIRO = "Africa/Cairo",
-    JOHANNESBURG = "Africa/Johannesburg",
-    LAGOS = "Africa/Lagos",
-    NAIROBI = "Africa/Nairobi",
-    CASABLANCA = "Africa/Casablanca",
-    ALGIERS = "Africa/Algiers",
-    TUNIS = "Africa/Tunis",
-    ADDIS_ABABA = "Africa/Addis_Ababa",
-    ACCRA = "Africa/Accra",
-    DAKAR = "Africa/Dakar",
-    LUANDA = "Africa/Luanda",
-    ANTANANARIVO = "Indian/Antananarivo",
-    KINSHASA = "Africa/Kinshasa",
-    DAR_ES_SALAAM = "Africa/Dar_es_Salaam",
-    MCMURDO = "Antarctica/McMurdo",
-    CASEY = "Antarctica/Casey"
-}
-/**
- * Type helper for secondaryTimeZone configuration
- * Allows using either the TimeZone enum or a raw IANA string.
- */
-type TimeZoneValue = TimeZone | string;
-
 /**
  * Common Props interface for view components
  * Base properties for all view components
@@ -1210,6 +1211,7 @@ interface DayViewConfig extends ViewFactoryConfig {
     showAllDay?: boolean;
     scrollToCurrentTime?: boolean;
     secondaryTimeZone?: TimeZoneValue;
+    showEventDots?: boolean;
 }
 /**
  * Week view factory configuration
@@ -1220,6 +1222,7 @@ interface WeekViewConfig extends ViewFactoryConfig {
     startOfWeek?: number;
     scrollToCurrentTime?: boolean;
     secondaryTimeZone?: TimeZoneValue;
+    showEventDots?: boolean;
 }
 /**
  * Month scroll / navigation configuration
@@ -1244,6 +1247,7 @@ interface MonthViewConfig extends ViewFactoryConfig {
     snapToMonth?: boolean;
     /** Scroll / navigation behavior for the month view */
     scroll?: MonthScrollConfig;
+    showEventDots?: boolean;
 }
 /**
  * Year view factory configuration
@@ -1254,12 +1258,9 @@ interface YearViewConfig extends ViewFactoryConfig {
     startOfWeek?: number;
     /** Scroll / navigation behavior for the month view */
     scroll?: MonthScrollConfig;
+    showEventDots?: boolean;
     /**
      * Grid mode: action when a date cell is clicked.
-     * - 'popup' (default): show a popup with events for that day
-     * - 'day-view': navigate to the Day View
-     * - 'none': no action
-     * - function: custom handler
      */
     gridDateClick?: 'popup' | 'day-view' | 'none' | ((date: Date, events: Event[]) => void);
     /**
@@ -1443,6 +1444,13 @@ interface DragPluginConfig {
     supportedViews: ViewType[];
     onEventDrop?: (updatedEvent: Event, originalEvent: Event) => void | Promise<void>;
     onEventResize?: (updatedEvent: Event, originalEvent: Event) => void | Promise<void>;
+    /**
+     * Controls cursor position relative to the drag indicator when dragging all-day events
+     * in month/year views.
+     * - `true` (default): cursor anchors to the start (left edge) of the indicator
+     * - `false`: cursor anchors to the center of the indicator
+     */
+    allDayDragCursorAtStart?: boolean;
     [key: string]: unknown;
 }
 /**
@@ -1524,27 +1532,19 @@ declare class CalendarApp implements ICalendarApp {
     state: CalendarAppState;
     private callbacks;
     private calendarRegistry;
-    private store;
-    private visibleMonth;
+    private themeChangeListeners;
+    private listeners;
+    private eventManager;
+    private navigation;
+    private pluginManager;
     private useEventDetailDialog;
     private useCalendarHeader;
     private customMobileEventRenderer?;
-    private themeChangeListeners;
-    private listeners;
-    private undoStack;
-    private pendingSnapshot;
-    private pendingChangeSource;
-    private readonly MAX_UNDO_STACK;
-    private externalEvents;
     constructor(config: CalendarAppConfig);
-    private setupStoreListeners;
     private static resolveLocale;
     subscribe: (listener: (app: ICalendarApp) => void) => (() => void);
     private notify;
-    private pushToUndo;
-    undo: () => void;
-    getReadOnlyConfig: () => ReadOnlyConfig;
-    canMutateFromUI: () => boolean;
+    triggerRender: () => void;
     changeView: (view: CalendarViewType) => void;
     getCurrentView: () => CalendarView;
     emitVisibleRange: (start: Date, end: Date, reason?: RangeChangeReason) => void;
@@ -1557,6 +1557,7 @@ declare class CalendarApp implements ICalendarApp {
     goToPrevious: () => void;
     goToNext: () => void;
     selectDate: (date: Date) => void;
+    undo: () => void;
     applyEventsChanges: (changes: {
         add?: Event[];
         update?: Array<{
@@ -1566,25 +1567,18 @@ declare class CalendarApp implements ICalendarApp {
         delete?: string[];
     }, isPending?: boolean, source?: "drag" | "resize") => void;
     addEvent: (event: Event) => void;
-    /**
-     * Add external events to the state without persisting to the core store.
-     * This is used for temporary/subscription-based events.
-     */
     addExternalEvents: (calendarId: string, events: Event[]) => void;
-    /**
-     * Synchronize all events (core + external) into the main state.events array.
-     * This ensures all views and plugins that listen to state.events see the combined list.
-     */
-    private syncExternalEventsToState;
     updateEvent: (id: string, eventUpdate: Partial<Event>, isPending?: boolean, source?: "drag" | "resize") => Promise<void>;
     deleteEvent: (id: string) => Promise<void>;
     getAllEvents: () => Event[];
+    getEvents: () => Event[];
     onEventClick: (event: Event) => void;
     onMoreEventsClick: (date: Date) => void;
     highlightEvent: (eventId: string | null) => void;
     selectEvent: (eventId: string | null) => void;
     dismissUI: () => void;
-    getEvents: () => Event[];
+    getReadOnlyConfig: (id?: string) => ReadOnlyConfig;
+    canMutateFromUI: (id?: string) => boolean;
     getCalendars: () => CalendarType[];
     reorderCalendars: (fromIndex: number, toIndex: number) => void;
     setCalendarVisibility: (calendarId: string, visible: boolean) => void;
@@ -1593,40 +1587,22 @@ declare class CalendarApp implements ICalendarApp {
     createCalendar: (calendar: CalendarType) => Promise<void>;
     deleteCalendar: (id: string) => Promise<void>;
     mergeCalendars: (sourceId: string, targetId: string) => Promise<void>;
-    getCalendarHeaderConfig: () => boolean | ((props: CalendarHeaderProps) => TNode);
-    private installPlugin;
     getPlugin: <T = unknown>(name: string) => T | undefined;
     hasPlugin: (name: string) => boolean;
     getPluginConfig: (pluginName: string) => Record<string, unknown>;
     updatePluginConfig: (pluginName: string, config: Record<string, unknown>) => void;
+    setTheme: (mode: ThemeMode) => void;
+    getTheme: () => ThemeMode;
+    subscribeThemeChange: (callback: (theme: ThemeMode) => void) => (() => void);
+    unsubscribeThemeChange: (callback: (theme: ThemeMode) => void) => void;
     getViewConfig: (viewType: CalendarViewType) => Record<string, unknown>;
-    triggerRender: () => void;
     getCalendarRegistry: () => CalendarRegistry;
     getUseEventDetailDialog: () => boolean;
     getCustomMobileEventRenderer: () => MobileEventRenderer | undefined;
-    updateConfig: (config: Partial<CalendarAppConfig>) => void;
+    getCalendarHeaderConfig: () => boolean;
+    get timeZone(): string;
     setOverrides: (overrides: string[]) => void;
-    /**
-     * Set theme mode
-     * @param mode - Theme mode ('light', 'dark', or 'auto')
-     */
-    setTheme: (mode: ThemeMode) => void;
-    /**
-     * Get current theme mode
-     * @returns Current theme mode
-     */
-    getTheme: () => ThemeMode;
-    /**
-     * Subscribe to theme changes
-     * @param callback - Function to call when theme changes
-     * @returns Unsubscribe function
-     */
-    subscribeThemeChange: (callback: (theme: ThemeMode) => void) => (() => void);
-    /**
-     * Unsubscribe from theme changes
-     * @param callback - Function to remove from listeners
-     */
-    unsubscribeThemeChange: (callback: (theme: ThemeMode) => void) => void;
+    updateConfig: (config: Partial<CalendarAppConfig>) => void;
 }
 
 interface CustomRendering {
@@ -1679,6 +1655,8 @@ declare class CalendarRenderer {
     private requestRender;
     /**
      * Mount the calendar to a DOM container.
+     * Renders synchronously so the content is in the DOM before the first paint.
+     * Subsequent updates (triggered by app state changes) still use requestAnimationFrame.
      */
     mount(container: HTMLElement): void;
     /**
@@ -1827,7 +1805,7 @@ declare const roundToTimeStep: (hour: number) => number;
 declare const generateSecondaryTimeSlots: (timeSlots: Array<{
     hour: number;
     label: string;
-}>, secondaryTimeZone: TimeZoneValue, timeFormat?: "12h" | "24h", referenceDate?: Date) => string[];
+}>, secondaryTimeZone: TimeZoneValue, timeFormat?: "12h" | "24h", referenceDate?: Date, baseTimeZone?: string) => string[];
 /**
  * Get a short display label for a timezone, e.g. "CST" or "GMT+8".
  *
@@ -1836,6 +1814,14 @@ declare const generateSecondaryTimeSlots: (timeSlots: Array<{
  * @returns Short timezone label
  */
 declare const getTimezoneDisplayLabel: (timeZone: TimeZoneValue, date?: Date) => string;
+declare const getNowInTimeZone: (timeZone?: TimeZoneValue) => Date;
+declare const getTodayInTimeZone: (timeZone?: TimeZoneValue) => Date;
+declare const getNextHourRangeInTimeZone: (timeZone?: TimeZoneValue) => {
+    start: Date;
+    end: Date;
+};
+declare const restoreVisualTimedTemporalToCanonical: (visualTemporal: Temporal.PlainDateTime | Temporal.ZonedDateTime | Date, originalTemporal: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime, appTimeZone?: TimeZoneValue) => Temporal.PlainDateTime | Temporal.ZonedDateTime;
+declare const restoreVisualEventToCanonical: (originalEvent: Event, visualEvent: Event, appTimeZone?: TimeZoneValue) => Event;
 
 /**
  * Date Constants
@@ -2170,6 +2156,17 @@ declare function isZonedDateTime(temporal: unknown): temporal is Temporal.ZonedD
  * Handles all three Temporal types and native Date uniformly
  */
 declare function temporalToDate(temporal: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime | Date): Date;
+/**
+ * Convert any Temporal type or Date to a "Visual" Date based on a target timezone.
+ * Unlike temporalToDate, this shifts the wall time to match the target timezone
+ * while returning a local Date object that reflects that shifted time.
+ */
+declare function temporalToVisualDate(temporal: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime | Date, targetTz?: string): Date;
+/**
+ * Convert any Temporal type to a "Visual" Temporal based on a target timezone.
+ * Unlike temporalToVisualDate, this returns a Temporal object (ZonedDateTime).
+ */
+declare function temporalToVisualTemporal(temporal: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime, targetTz?: string): Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime;
 /**
  * Convert Date to PlainDate (for all-day events)
  */
@@ -2813,6 +2810,8 @@ interface RestoredTimedDragState {
 }
 declare const restoreTimedDragFromAllDayTransition: ({ wasOriginallyAllDay, mouseHour, hourOffset, duration, originalStartHour, originalEndHour, firstHour, lastHour, minDuration, roundToTimeStep, }: RestoreTimedDragOptions) => RestoredTimedDragState;
 
+declare function normalizeTimeZoneValue(timeZone?: TimeZoneValue): string | undefined;
+
 interface SubscribeResult {
     calendar: CalendarType;
     events: Event[];
@@ -3036,8 +3035,12 @@ interface MiniCalendarProps {
     onMonthChange: (offset: number) => void;
     onDateSelect: (date: Date) => void;
     locale?: string;
+    events?: Event[];
+    showEventDots?: boolean;
+    calendarRegistry?: CalendarRegistry;
+    timeZone?: string;
 }
-declare const MiniCalendar: ({ visibleMonth, currentDate, showHeader, onMonthChange, onDateSelect, }: MiniCalendarProps) => preact.JSX.Element;
+declare const MiniCalendar: ({ visibleMonth, currentDate, showHeader, onMonthChange, onDateSelect, events, showEventDots, calendarRegistry, timeZone, }: MiniCalendarProps) => preact.JSX.Element;
 
 declare const CreateCalendarDialog: ({ onClose, onCreate, app, }: CreateCalendarDialogProps) => preact.VNode<any> | null;
 
@@ -3159,9 +3162,11 @@ interface CalendarEventProps {
     renderVisualContent?: (defaultContent: ComponentChildren) => ComponentChildren;
     /** Override resize handle orientation for custom views */
     resizeHandleOrientation?: 'vertical' | 'horizontal';
+    /** App-level timezone used to project event times for display (Month/Year view). */
+    appTimeZone?: string;
 }
 
-declare const CalendarEvent: ({ event, layout, isAllDay, allDayHeight, calendarRef, isBeingDragged, isBeingResized, viewType, isMultiDay, segment, yearSegment, columnsPerRow, segmentIndex, hourHeight, firstHour, selectedEventId, detailPanelEventId, onMoveStart, onResizeStart, onEventUpdate, onEventDelete, newlyCreatedEventId, onDetailPanelOpen, onEventSelect, onEventLongPress, onDetailPanelToggle, customDetailPanelContent, customEventDetailDialog, multiDaySegmentInfo, app, isMobile, isSlidingView, enableTouch, hideTime, timeFormat, styleOverride, className, disableDefaultStyle, renderVisualContent, resizeHandleOrientation, }: CalendarEventProps) => preact.JSX.Element;
+declare const CalendarEvent: ({ event, layout, isAllDay, allDayHeight, calendarRef, isBeingDragged, isBeingResized, viewType, isMultiDay, segment, yearSegment, columnsPerRow, segmentIndex, hourHeight, firstHour, selectedEventId, detailPanelEventId, onMoveStart, onResizeStart, onEventUpdate, onEventDelete, newlyCreatedEventId, onDetailPanelOpen, onEventSelect, onEventLongPress, onDetailPanelToggle, customDetailPanelContent, customEventDetailDialog, multiDaySegmentInfo, app, isMobile, isSlidingView, enableTouch, hideTime, timeFormat, styleOverride, className, disableDefaultStyle, renderVisualContent, resizeHandleOrientation, appTimeZone, }: CalendarEventProps) => preact.JSX.Element;
 
 interface IconProps {
     className?: string;
@@ -3205,5 +3210,5 @@ declare const sidebarHeaderToggle = "df-sidebar-header-toggle flex h-8 w-8 items
  */
 declare const sidebarHeaderTitle = "df-sidebar-header-title text-sm font-semibold text-gray-700 dark:text-gray-200";
 
-export { AlertCircle, AudioLines, BlossomColorPicker, CalendarApp, CalendarEvent, CalendarRegistry, CalendarRenderer, Check, ChevronDown, ChevronRight, ChevronsUpDown, ContentSlot, ContextMenu, ContextMenuColorPicker, ContextMenuItem, ContextMenuLabel, ContextMenuSeparator, CreateCalendarDialog, CustomRenderingStore, RangePicker as DayflowRangePicker, DefaultColorPicker, DefaultEventDetailDialog, DefaultEventDetailPanel, EventContextMenu, GridContextMenu, LAYOUT_CONFIG, LOCALES, Loader2, LoadingButton, LocaleContext, LocaleProvider, MiniCalendar, PanelRightClose, PanelRightOpen, Plus, TIME_STEP, TimeZone, VIRTUAL_MONTH_SCROLL_CONFIG, ViewType, WeekDataCache, addDays, buildParseRegExp, calculateDayIndex, calendarPickerDropdown, cancelButton, capitalize, clipboardStore, compareAllDayDisplayPriority, conditionalTheme, convertDateEvent, convertDateEventWithTimeZone, convertToDayFlowEvent, createAllDayDisplayComparator, 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, getAllDayRangeMetrics, 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, restoreTimedDragFromAllDayTransition, roundToTimeStep, scrollbarTakesSpace, setHourInTemporal, shortMonthNames, sidebarContainer, sidebarHeader, sidebarHeaderTitle, sidebarHeaderToggle, sortAllDayByTitle, subscribeCalendar, t, temporalToDate, themeClasses, themeCn, today, unescapeICSValue, updateEventDateAndDay, updateEventWithRealDate, useDragForView, useLocale, useSidebarBridge, weekDays, weekDaysFullName, zonedDateTimeToDate };
+export { AlertCircle, AudioLines, BlossomColorPicker, CalendarApp, CalendarEvent, CalendarRegistry, CalendarRenderer, Check, ChevronDown, ChevronRight, ChevronsUpDown, ContentSlot, ContextMenu, ContextMenuColorPicker, ContextMenuItem, ContextMenuLabel, ContextMenuSeparator, CreateCalendarDialog, CustomRenderingStore, RangePicker as DayflowRangePicker, DefaultColorPicker, DefaultEventDetailDialog, DefaultEventDetailPanel, EventContextMenu, GridContextMenu, LAYOUT_CONFIG, LOCALES, Loader2, LoadingButton, LocaleContext, LocaleProvider, MiniCalendar, PanelRightClose, PanelRightOpen, Plus, TIME_STEP, TimeZone, VIRTUAL_MONTH_SCROLL_CONFIG, ViewType, WeekDataCache, addDays, buildParseRegExp, calculateDayIndex, calendarPickerDropdown, cancelButton, capitalize, clipboardStore, compareAllDayDisplayPriority, conditionalTheme, convertDateEvent, convertDateEventWithTimeZone, convertToDayFlowEvent, createAllDayDisplayComparator, 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, getAllDayRangeMetrics, getCalendarColorsForHex, getCurrentWeekDates, getDateByDayIndex, getDateObj, getDayIndexByDate, getEndOfDay, getEndOfTemporal, getEventBgColor, getEventEndHour, getEventTextColor, getEventsForDay, getEventsForWeek, getIntlLabel, getLineColor, getMonthLabels, getMonthYearOfWeek, getNextHourRangeInTimeZone, getNowInTimeZone, getPlainDate, getSearchHeaderInfo, getSelectedBgColor, getStartOfDay, getStartOfTemporal, getTestEvents, getTimezoneDisplayLabel, getTodayInTimeZone, 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, normalizeTimeZoneValue, normalizeToZoned, now, pad, pad2, parseICS, parseICSDate, parseTemporalString, parseVEventLines, plainDateTimeToDate, plainDateToDate, recalculateEventDays, registerDragImplementation, registerLocale, registerSidebarImplementation, resolveAppliedTheme, restoreTimedDragFromAllDayTransition, restoreVisualEventToCanonical, restoreVisualTimedTemporalToCanonical, roundToTimeStep, scrollbarTakesSpace, setHourInTemporal, shortMonthNames, sidebarContainer, sidebarHeader, sidebarHeaderTitle, sidebarHeaderToggle, sortAllDayByTitle, subscribeCalendar, t, temporalToDate, temporalToVisualDate, temporalToVisualTemporal, themeClasses, themeCn, today, unescapeICSValue, updateEventDateAndDay, updateEventWithRealDate, useDragForView, useLocale, useSidebarBridge, weekDays, weekDaysFullName, zonedDateTimeToDate };
 export type { AllDaySortComparator, BalanceStrategy, BaseViewProps, CalendarAppConfig, CalendarAppState, CalendarCallbacks, CalendarColors, CalendarConfig, CalendarEventProps, CalendarHeaderProps, CalendarPlugin, CalendarType, CalendarView, CalendarViewType, 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, MonthScrollConfig, MonthViewConfig, MonthViewProps, NestedLayer, RangeChangeReason, RangePickerProps, ReadOnlyConfig, SidebarBridgeReturn, SidebarHeaderSlotArgs, SpecialLayoutRule, SubscribeResult, 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, ZonedRange, useDragProps, useDragReturn };