@forcecalendar/core 2.1.70 → 2.2.0

package/types/calendar/Calendar.d.ts

@@ -0,0 +1,287 @@
+import { EventStore } from '../events/EventStore.js';
+import { Event } from '../events/Event.js';
+import { StateManager } from '../state/StateManager.js';
+import { TimezoneManager } from '../timezone/TimezoneManager.js';
+/**
+ * Calendar - Main calendar class with full timezone support
+ * Pure JavaScript, no DOM dependencies
+ * Framework agnostic, Locker Service compatible
+ */
+export declare class Calendar {
+    timezoneManager: TimezoneManager;
+    config: {
+        events?: import("../types.js").EventData[];
+        view: string;
+        date: Date;
+        weekStartsOn: number;
+        locale: string;
+        timeZone: string;
+        showWeekNumbers: boolean;
+        showWeekends: boolean;
+        fixedWeekCount: boolean;
+        businessHours: {
+            start: string;
+            end: string;
+        };
+    };
+    eventStore: EventStore;
+    state: StateManager;
+    listeners: Map<any, any>;
+    plugins: Set<any>;
+    views: Map<any, any>;
+    /**
+     * Create a new Calendar instance
+     * @param {import('../types.js').CalendarConfig} [config={}] - Configuration options
+     */
+    constructor(config?: import('../types.js').CalendarConfig);
+    /**
+     * Set the calendar view
+     * @param {import('../types.js').ViewType} viewType - The view type ('month', 'week', 'day', 'list')
+     * @param {Date} [date=null] - Optional date to navigate to
+     */
+    setView(viewType: import('../types.js').ViewType, date?: Date): void;
+    /**
+     * Get the current view type
+     * @returns {import('../types.js').ViewType} The current view type
+     */
+    getView(): import('../types.js').ViewType;
+    /**
+     * Navigate to the next period
+     */
+    next(): void;
+    /**
+     * Navigate to the previous period
+     */
+    previous(): void;
+    /**
+     * Navigate to today
+     */
+    today(): void;
+    /**
+     * Navigate to a specific date
+     * @param {Date} date - The date to navigate to
+     */
+    goToDate(date: Date): void;
+    /**
+     * Alias for goToDate (compat)
+     * @param {Date} date - The date to navigate to
+     */
+    setDate(date: Date): void;
+    /**
+     * Get the current date
+     * @returns {Date}
+     */
+    getCurrentDate(): Date;
+    /**
+     * Add an event
+     * @param {import('../events/Event.js').Event|import('../types.js').EventData} eventData - Event data or Event instance
+     * @returns {import('../events/Event.js').Event} The added event
+     */
+    addEvent(eventData: import('../events/Event.js').Event | import('../types.js').EventData): import('../events/Event.js').Event;
+    /**
+     * Update an event
+     * @param {string} eventId - The event ID
+     * @param {Object} updates - Properties to update
+     * @returns {Event} The updated event
+     */
+    updateEvent(eventId: string, updates: Object): Event;
+    /**
+     * Remove an event
+     * @param {string} eventId - The event ID
+     * @returns {boolean} True if removed
+     */
+    removeEvent(eventId: string): boolean;
+    /**
+     * Alias for removeEvent (compat)
+     * @param {string} eventId - The event ID
+     * @returns {boolean} True if removed
+     */
+    deleteEvent(eventId: string): boolean;
+    /**
+     * Get an event by ID
+     * @param {string} eventId - The event ID
+     * @returns {Event|null}
+     */
+    getEvent(eventId: string): Event | null;
+    /**
+     * Get all events
+     * @returns {Event[]}
+     */
+    getEvents(): Event[];
+    /**
+     * Set all events (replaces existing)
+     * @param {Event[]} events - Array of events
+     */
+    setEvents(events: Event[]): void;
+    /**
+     * Query events with filters
+     * @param {Object} filters - Query filters
+     * @returns {Event[]}
+     */
+    queryEvents(filters: Object): Event[];
+    /**
+     * Get events for a specific date
+     * @param {Date} date - The date
+     * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
+     * @returns {Event[]}
+     */
+    getEventsForDate(date: Date, timezone?: string): Event[];
+    /**
+     * Get events in a date range
+     * @param {Date} start - Start date
+     * @param {Date} end - End date
+     * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
+     * @returns {Event[]}
+     */
+    getEventsInRange(start: Date, end: Date, timezone?: string): Event[];
+    /**
+     * Set the calendar's timezone
+     * @param {string} timezone - IANA timezone identifier
+     */
+    setTimezone(timezone: string): void;
+    /**
+     * Get the current timezone
+     * @returns {string} Current timezone
+     */
+    getTimezone(): string;
+    /**
+     * Set the calendar locale
+     * @param {string} locale - Locale identifier (e.g. 'en-US')
+     */
+    setLocale(locale: string): void;
+    /**
+     * Set the week start day
+     * @param {number} weekStartsOn - 0 = Sunday, 1 = Monday, etc.
+     */
+    setWeekStartsOn(weekStartsOn: number): void;
+    /**
+     * Convert a date from one timezone to another
+     * @param {Date} date - Date to convert
+     * @param {string} fromTimezone - Source timezone
+     * @param {string} toTimezone - Target timezone
+     * @returns {Date} Converted date
+     */
+    convertTimezone(date: Date, fromTimezone: string, toTimezone: string): Date;
+    /**
+     * Convert a date to the calendar's timezone
+     * @param {Date} date - Date to convert
+     * @param {string} fromTimezone - Source timezone
+     * @returns {Date} Date in calendar timezone
+     */
+    toCalendarTimezone(date: Date, fromTimezone: string): Date;
+    /**
+     * Convert a date from the calendar's timezone
+     * @param {Date} date - Date in calendar timezone
+     * @param {string} toTimezone - Target timezone
+     * @returns {Date} Converted date
+     */
+    fromCalendarTimezone(date: Date, toTimezone: string): Date;
+    /**
+     * Format a date in a specific timezone
+     * @param {Date} date - Date to format
+     * @param {string} [timezone] - Timezone for formatting (defaults to calendar timezone)
+     * @param {Object} [options] - Formatting options
+     * @returns {string} Formatted date string
+     */
+    formatInTimezone(date: Date, timezone?: string, options?: Object): string;
+    /**
+     * Get list of common timezones with offsets
+     * @returns {Array<{value: string, label: string, offset: string}>} Timezone list
+     */
+    getTimezones(): Array<{
+        value: string;
+        label: string;
+        offset: string;
+    }>;
+    /**
+     * Get overlapping event groups for a date
+     * @param {Date} date - The date to check
+     * @param {boolean} timedOnly - Only include timed events
+     * @returns {Array<Event[]>} Array of event groups that overlap
+     */
+    getOverlapGroups(date: Date, timedOnly?: boolean): Array<Event[]>;
+    /**
+     * Calculate event positions for rendering
+     * @param {Event[]} events - Array of overlapping events
+     * @returns {Map<string, {column: number, totalColumns: number}>} Position data
+     */
+    calculateEventPositions(events: Event[]): Map<string, {
+        column: number;
+        totalColumns: number;
+    }>;
+    /**
+     * Get the current view's data
+     * @returns {import('../types.js').MonthViewData|import('../types.js').WeekViewData|import('../types.js').DayViewData|import('../types.js').ListViewData|null} View-specific data
+     */
+    getViewData(): import('../types.js').MonthViewData | import('../types.js').WeekViewData | import('../types.js').DayViewData | import('../types.js').ListViewData | null;
+    /**
+     * Get month view data
+     * @private
+     */
+    private _getMonthViewData;
+    /**
+     * Get week view data
+     * @private
+     */
+    private _getWeekViewData;
+    /**
+     * Get day view data
+     * @private
+     */
+    private _getDayViewData;
+    /**
+     * Get list view data
+     * @private
+     */
+    private _getListViewData;
+    /**
+     * Select an event
+     * @param {string} eventId - Event ID to select
+     */
+    selectEvent(eventId: string): void;
+    /**
+     * Clear event selection
+     */
+    clearEventSelection(): void;
+    /**
+     * Select a date
+     * @param {Date} date - Date to select
+     */
+    selectDate(date: Date): void;
+    /**
+     * Clear date selection
+     */
+    clearDateSelection(): void;
+    /**
+     * Subscribe to calendar events
+     * @param {string} eventName - Event name
+     * @param {Function} callback - Callback function
+     * @returns {Function} Unsubscribe function
+     */
+    on(eventName: string, callback: Function): Function;
+    /**
+     * Unsubscribe from calendar events
+     * @param {string} eventName - Event name
+     * @param {Function} callback - Callback function
+     */
+    off(eventName: string, callback: Function): void;
+    /**
+     * Emit an event
+     * @private
+     */
+    private _emit;
+    /**
+     * Set up internal listeners
+     * @private
+     */
+    private _setupInternalListeners;
+    /**
+     * Install a plugin
+     * @param {Object} plugin - Plugin object with install method
+     */
+    use(plugin: Object): void;
+    /**
+     * Destroy the calendar and clean up
+     */
+    destroy(): void;
+}

package/types/calendar/DateUtils.d.ts

@@ -0,0 +1,298 @@
+/**
+ * DateUtils - Date manipulation utilities
+ * Pure functions, no external dependencies
+ * Locker Service compatible
+ */
+export declare class DateUtils {
+    /**
+     * Get the start of a day
+     * @param {Date} date - The date
+     * @returns {Date}
+     */
+    static startOfDay(date: Date): Date;
+    /**
+     * Get the end of a day
+     * @param {Date} date - The date
+     * @returns {Date}
+     */
+    static endOfDay(date: Date): Date;
+    /**
+     * Get the start of a week
+     * @param {Date} date - The date
+     * @param {number} [weekStartsOn=0] - 0 = Sunday, 1 = Monday, etc.
+     * @returns {Date} Start of the week
+     */
+    static startOfWeek(date: Date, weekStartsOn?: number): Date;
+    /**
+     * Get the end of a week
+     * @param {Date} date - The date
+     * @param {number} weekStartsOn - 0 = Sunday, 1 = Monday, etc.
+     * @returns {Date}
+     */
+    static endOfWeek(date: Date, weekStartsOn?: number): Date;
+    /**
+     * Get the start of a month
+     * @param {Date} date - The date
+     * @returns {Date}
+     */
+    static startOfMonth(date: Date): Date;
+    /**
+     * Get the end of a month
+     * @param {Date} date - The date
+     * @returns {Date}
+     */
+    static endOfMonth(date: Date): Date;
+    /**
+     * Get the start of a year
+     * @param {Date} date - The date
+     * @returns {Date}
+     */
+    static startOfYear(date: Date): Date;
+    /**
+     * Get the end of a year
+     * @param {Date} date - The date
+     * @returns {Date}
+     */
+    static endOfYear(date: Date): Date;
+    /**
+     * Add days to a date
+     * @param {Date} date - The date
+     * @param {number} days - Number of days to add (can be negative)
+     * @returns {Date}
+     */
+    static addDays(date: Date, days: number): Date;
+    /**
+     * Add weeks to a date
+     * @param {Date} date - The date
+     * @param {number} weeks - Number of weeks to add
+     * @returns {Date}
+     */
+    static addWeeks(date: Date, weeks: number): Date;
+    /**
+     * Add months to a date
+     * @param {Date} date - The date
+     * @param {number} months - Number of months to add
+     * @returns {Date}
+     */
+    static addMonths(date: Date, months: number): Date;
+    /**
+     * Add years to a date
+     * @param {Date} date - The date
+     * @param {number} years - Number of years to add
+     * @returns {Date}
+     */
+    static addYears(date: Date, years: number): Date;
+    /**
+     * Get a consistent UTC date string for indexing (YYYY-MM-DD format)
+     * @param {Date} date - The date
+     * @returns {string} UTC date string
+     */
+    static getUTCDateString(date: Date): string;
+    /**
+     * Get a consistent local date string for indexing (YYYY-MM-DD format)
+     * @param {Date} date - The date
+     * @returns {string} Local date string
+     */
+    static getLocalDateString(date: Date): string;
+    /**
+     * Check if a date is today
+     * @param {Date} date - The date to check
+     * @returns {boolean}
+     */
+    static isToday(date: Date): boolean;
+    /**
+     * Check if a date is in the past
+     * @param {Date} date - The date to check
+     * @returns {boolean}
+     */
+    static isPast(date: Date): boolean;
+    /**
+     * Check if a date is in the future
+     * @param {Date} date - The date to check
+     * @returns {boolean}
+     */
+    static isFuture(date: Date): boolean;
+    /**
+     * Check if two dates are on the same day
+     * @param {Date} date1 - First date
+     * @param {Date} date2 - Second date
+     * @returns {boolean}
+     */
+    static isSameDay(date1: Date, date2: Date): boolean;
+    /**
+     * Check if two dates are in the same week
+     * @param {Date} date1 - First date
+     * @param {Date} date2 - Second date
+     * @param {number} weekStartsOn - 0 = Sunday, 1 = Monday, etc.
+     * @returns {boolean}
+     */
+    static isSameWeek(date1: Date, date2: Date, weekStartsOn?: number): boolean;
+    /**
+     * Check if two dates are in the same month
+     * @param {Date} date1 - First date
+     * @param {Date} date2 - Second date
+     * @returns {boolean}
+     */
+    static isSameMonth(date1: Date, date2: Date): boolean;
+    /**
+     * Check if two dates are in the same year
+     * @param {Date} date1 - First date
+     * @param {Date} date2 - Second date
+     * @returns {boolean}
+     */
+    static isSameYear(date1: Date, date2: Date): boolean;
+    /**
+     * Get the difference in days between two dates
+     * @param {Date} date1 - First date
+     * @param {Date} date2 - Second date
+     * @returns {number}
+     */
+    static differenceInDays(date1: Date, date2: Date): number;
+    /**
+     * Get the difference in weeks between two dates
+     * @param {Date} date1 - First date
+     * @param {Date} date2 - Second date
+     * @returns {number}
+     */
+    static differenceInWeeks(date1: Date, date2: Date): number;
+    /**
+     * Get the difference in months between two dates
+     * @param {Date} date1 - First date
+     * @param {Date} date2 - Second date
+     * @returns {number}
+     */
+    static differenceInMonths(date1: Date, date2: Date): number;
+    /**
+     * Get the week number of a date
+     * @param {Date} date - The date
+     * @returns {number}
+     */
+    static getWeekNumber(date: Date): number;
+    /**
+     * Get the day of week for a date
+     * @param {Date} date - The date
+     * @param {number} weekStartsOn - 0 = Sunday, 1 = Monday, etc.
+     * @returns {number} 0-6 where 0 is the first day of the week
+     */
+    static getDayOfWeek(date: Date, weekStartsOn?: number): number;
+    /**
+     * Get days in a month
+     * @param {Date} date - Any date in the month
+     * @returns {number}
+     */
+    static getDaysInMonth(date: Date): number;
+    /**
+     * Format a date using Intl.DateTimeFormat
+     * @param {Date} date - The date to format
+     * @param {string} locale - The locale
+     * @param {Object} options - Intl.DateTimeFormat options
+     * @returns {string}
+     */
+    static format(date: Date, locale?: string, options?: Object): string;
+    /**
+     * Get month name
+     * @param {Date} date - The date
+     * @param {string} locale - The locale
+     * @param {string} format - 'long', 'short', or 'narrow'
+     * @returns {string}
+     */
+    static getMonthName(date: Date, locale?: string, format?: string): string;
+    /**
+     * Get day name
+     * @param {Date} date - The date
+     * @param {string} locale - The locale
+     * @param {string} format - 'long', 'short', or 'narrow'
+     * @returns {string}
+     */
+    static getDayName(date: Date, locale?: string, format?: string): string;
+    /**
+     * Format time
+     * @param {Date} date - The date
+     * @param {string} locale - The locale
+     * @param {boolean} use24Hour - Use 24-hour format
+     * @returns {string}
+     */
+    static formatTime(date: Date, locale?: string, use24Hour?: boolean): string;
+    /**
+     * Parse a time string (HH:MM) to hours and minutes
+     * @param {string} timeString - Time string like "09:30"
+     * @returns {{hours: number, minutes: number}}
+     */
+    static parseTime(timeString: string): {
+        hours: number;
+        minutes: number;
+    };
+    /**
+     * Set time on a date
+     * @param {Date} date - The date
+     * @param {string} timeString - Time string like "09:30"
+     * @returns {Date}
+     */
+    static setTime(date: Date, timeString: string): Date;
+    /**
+     * Check if a year is a leap year
+     * @param {number} year - The year
+     * @returns {boolean}
+     */
+    static isLeapYear(year: number): boolean;
+    /**
+     * Get an array of dates between start and end
+     * @param {Date} start - Start date
+     * @param {Date} end - End date
+     * @returns {Date[]}
+     */
+    static getDateRange(start: Date, end: Date): Date[];
+    /**
+     * Clone a date
+     * @param {Date} date - The date to clone
+     * @returns {Date}
+     */
+    static clone(date: Date): Date;
+    /**
+     * Validate if a value is a valid date
+     * @param {*} value - Value to check
+     * @returns {boolean}
+     */
+    static isValidDate(value: any): boolean;
+    /**
+     * Convert a date to a specific timezone
+     * @param {Date} date - The date to convert
+     * @param {string} timeZone - IANA timezone string (e.g., 'America/New_York')
+     * @returns {Date} - Date object adjusted for timezone
+     */
+    static toTimeZone(date: Date, timeZone: string): Date;
+    /**
+     * Get timezone offset in minutes for a date
+     * @param {Date} date - The date
+     * @param {string} timeZone - IANA timezone string
+     * @returns {number} - Offset in minutes
+     */
+    static getTimezoneOffset(date: Date, timeZone: string): number;
+    /**
+     * Check if DST is in effect for a date in a timezone
+     * @param {Date} date - The date to check
+     * @param {string} timeZone - IANA timezone string
+     * @returns {boolean}
+     */
+    static isDST(date: Date, timeZone: string): boolean;
+    /**
+     * Add time accounting for DST transitions
+     * @param {Date} date - The date
+     * @param {number} hours - Hours to add
+     * @param {string} timeZone - IANA timezone string
+     * @returns {Date}
+     */
+    static addHoursWithDST(date: Date, hours: number, _timeZone: any): Date;
+    /**
+     * Create a date in a specific timezone
+     * @param {number} year
+     * @param {number} month - 0-indexed
+     * @param {number} day
+     * @param {number} hour
+     * @param {number} minute
+     * @param {number} second
+     * @param {string} timeZone - IANA timezone string
+     * @returns {Date}
+     */
+    static createInTimeZone(year: number, month: number, day: number, hour: number | undefined, minute: number | undefined, second: number | undefined, timeZone: string): Date;
+}

package/types/conflicts/ConflictDetector.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ConflictDetector - Detects scheduling conflicts between events
+ * Checks for time overlaps, attendee conflicts, and resource conflicts
+ */
+export declare class ConflictDetector {
+    eventStore: import("../index.js").EventStore;
+    conflictIdCounter: number;
+    /**
+     * Create a new ConflictDetector
+     * @param {import('../events/EventStore.js').EventStore} eventStore - Event store instance
+     */
+    constructor(eventStore: import('../events/EventStore.js').EventStore);
+    /**
+     * Check for conflicts for a specific event
+     * @param {import('../events/Event.js').Event|import('../types.js').EventData} event - Event to check
+     * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+     * @returns {import('../types.js').ConflictSummary} Conflict summary
+     */
+    checkConflicts(event: import('../events/Event.js').Event | import('../types.js').EventData, options?: import('../types.js').ConflictCheckOptions): import('../types.js').ConflictSummary;
+    /**
+     * Check for conflicts between two specific events
+     * @param {import('../events/Event.js').Event} event1 - First event
+     * @param {import('../events/Event.js').Event} event2 - Second event
+     * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+     * @returns {import('../types.js').ConflictDetails[]} Array of conflicts
+     */
+    checkEventPairConflicts(event1: import('../events/Event.js').Event, event2: import('../events/Event.js').Event, options?: import('../types.js').ConflictCheckOptions): import('../types.js').ConflictDetails[];
+    /**
+     * Get busy periods for a set of attendees
+     * @param {string[]} attendeeEmails - Attendee email addresses
+     * @param {Date} start - Start of period
+     * @param {Date} end - End of period
+     * @param {Object} [options={}] - Options
+     * @returns {Array<{start: Date, end: Date, eventIds: string[]}>} Busy periods
+     */
+    getBusyPeriods(attendeeEmails: string[], start: Date, end: Date, options?: Object): Array<{
+        start: Date;
+        end: Date;
+        eventIds: string[];
+    }>;
+    /**
+     * Get free time slots
+     * @param {Date} start - Start of search period
+     * @param {Date} end - End of search period
+     * @param {number} duration - Required duration in minutes
+     * @param {Object} [options={}] - Options
+     * @returns {Array<{start: Date, end: Date}>} Free time slots
+     */
+    getFreePeriods(start: Date, end: Date, duration: number, options?: Object): Array<{
+        start: Date;
+        end: Date;
+    }>;
+    /**
+     * Detect conflicts between two events
+     * @private
+     */
+    private _detectEventConflicts;
+    /**
+     * Check for time overlap between events
+     * @private
+     */
+    private _checkTimeOverlap;
+    /**
+     * Create time conflict details
+     * @private
+     */
+    private _createTimeConflict;
+    /**
+     * Check for attendee conflicts
+     * @private
+     */
+    private _checkAttendeeConflicts;
+    /**
+     * Check for resource conflicts
+     * @private
+     */
+    private _checkResourceConflicts;
+    /**
+     * Check for location conflicts
+     * @private
+     */
+    private _checkLocationConflict;
+    /**
+     * Build conflict summary
+     * @private
+     */
+    private _buildConflictSummary;
+    /**
+     * Merge overlapping busy periods
+     * @private
+     */
+    private _mergeBusyPeriods;
+    /**
+     * Get all busy periods
+     * @private
+     */
+    private _getAllBusyPeriods;
+    /**
+     * Check if time period is within business hours
+     * @private
+     */
+    private _isWithinBusinessHours;
+}