@forcecalendar/core 2.1.70 → 2.3.0

package/core/timezone/TimezoneManager.js

@@ -47,6 +47,11 @@ export class TimezoneManager {
     // so formatters are cached per timezone and reused
     this.formatterCache = new Map();
 
+    // Discovered offset-transition instants per zone:
+    // Map<timezone, {from: number, to: number, transitions: number[]}>
+    // covering [from, to] with a sorted list of transition timestamps
+    this.transitionCache = new Map();
+
     // Cache size management
     this.maxCacheSize = 1000;
     // ~20k 15-minute buckets per zone (≈ a few hundred KB worst case) covers
@@ -165,7 +170,11 @@ export class TimezoneManager {
           }
         }
         const tzDate = new Date(year, month - 1, day, hour, minute, second);
-        offset = -((tzDate.getTime() - date.getTime()) / (1000 * 60));
+        // formatToParts carries no milliseconds, so compare against the
+        // whole-second part of the input or sub-second noise leaks into
+        // the offset (e.g. 660.0042 instead of 660)
+        const wholeSecondMs = Math.floor(date.getTime() / 1000) * 1000;
+        offset = -((tzDate.getTime() - wholeSecondMs) / (1000 * 60));
       } catch (e) {
         // Fallback to database calculation
       }
@@ -193,6 +202,74 @@ export class TimezoneManager {
     return offset;
   }
 
+  /**
+   * Find the next instant at which the zone's UTC offset changes
+   * @param {string} timezone - Timezone identifier
+   * @param {number} fromMs - Search from this timestamp (exclusive)
+   * @param {number} toMs - Search up to this timestamp (inclusive)
+   * @returns {number} Timestamp of the first offset change after fromMs, or Infinity
+   */
+  getNextTransition(timezone, fromMs, toMs) {
+    if (fromMs >= toMs) {
+      return Infinity;
+    }
+    timezone = this.database.resolveAlias(timezone);
+    let cached = this.transitionCache.get(timezone);
+    if (!cached || fromMs < cached.from || toMs > cached.to) {
+      // Extend coverage generously so repeated expansions over the same
+      // span hit the cache
+      const from = Math.min(fromMs, cached ? cached.from : fromMs);
+      const to = Math.max(toMs, cached ? cached.to : toMs);
+      cached = { from, to, transitions: this._scanTransitions(timezone, from, to) };
+      this.transitionCache.set(timezone, cached);
+    }
+    for (const t of cached.transitions) {
+      if (t > fromMs) {
+        return t <= toMs ? t : Infinity;
+      }
+    }
+    return Infinity;
+  }
+
+  /**
+   * Scan a range for offset transitions. Probes in 7-day steps (shorter
+   * than any gap between real-world transitions, including Ramadan DST
+   * suspensions) and binary-searches each change to the exact instant.
+   * @param {string} timezone - Resolved timezone identifier
+   * @param {number} fromMs - Range start
+   * @param {number} toMs - Range end
+   * @returns {number[]} Sorted transition timestamps
+   * @private
+   */
+  _scanTransitions(timezone, fromMs, toMs) {
+    const WEEK = 7 * 86400000;
+    const transitions = [];
+    const offsetAt = ms => this.getTimezoneOffset(new Date(ms), timezone);
+    let lo = fromMs;
+    let loOffset = offsetAt(lo);
+    while (lo < toMs) {
+      const hi = Math.min(lo + WEEK, toMs);
+      const hiOffset = offsetAt(hi);
+      if (hiOffset !== loOffset) {
+        // Binary search for the first ms with the new offset
+        let a = lo;
+        let b = hi;
+        while (b - a > 1) {
+          const mid = Math.floor((a + b) / 2);
+          if (offsetAt(mid) === loOffset) {
+            a = mid;
+          } else {
+            b = mid;
+          }
+        }
+        transitions.push(b);
+        loOffset = hiOffset;
+      }
+      lo = hi;
+    }
+    return transitions;
+  }
+
   /**
    * Get a cached Intl.DateTimeFormat for a timezone
    * @param {string} timezone - Timezone identifier
@@ -471,6 +548,7 @@ export class TimezoneManager {
   clearCache() {
     this.offsetCache.clear();
     this.dstCache.clear();
+    this.transitionCache.clear();
     this.cacheHits = 0;
     this.cacheMisses = 0;
   }

package/core/types.js

@@ -19,6 +19,9 @@
  * @property {boolean} [recurring=false] - Whether this is a recurring event
  * @property {RecurrenceRule|string} [recurrenceRule=null] - Recurrence rule (RRULE string or object)
  * @property {string} [timeZone=null] - IANA timezone for the event
+ * @property {string} [endTimeZone=null] - IANA timezone for the event end (cross-timezone events)
+ * @property {RecurrenceRule|string} [recurrence=null] - Backward-compatible alias for recurrenceRule
+ * @property {string} [category=null] - Single category (alias for a one-element categories array)
  * @property {EventStatus} [status='confirmed'] - Event status
  * @property {EventVisibility} [visibility='public'] - Event visibility
  * @property {Organizer} [organizer=null] - Event organizer
@@ -172,7 +175,7 @@
  * @property {boolean} isCurrentMonth - Whether this day is in the current month
  * @property {boolean} isToday - Whether this is today
  * @property {boolean} isWeekend - Whether this is a weekend day
- * @property {import('./core/events/Event.js').Event[]} events - Events for this day
+ * @property {import('./events/Event.js').Event[]} events - Events for this day
  */
 
 /**
@@ -191,9 +194,9 @@
  * @property {string} dayName - Localized day name
  * @property {boolean} isToday - Whether this is today
  * @property {boolean} isWeekend - Whether this is a weekend day
- * @property {import('./core/events/Event.js').Event[]} events - All events for this day
- * @property {Array<import('./core/events/Event.js').Event[]>} overlapGroups - Groups of overlapping events
- * @property {function(import('./core/events/Event.js').Event[]): Map<string, EventPosition>} getEventPositions - Function to calculate positions
+ * @property {import('./events/Event.js').Event[]} events - All events for this day
+ * @property {Array<import('./events/Event.js').Event[]>} overlapGroups - Groups of overlapping events
+ * @property {(events: import('./events/Event.js').Event[]) => Map<string, EventPosition>} getEventPositions - Function to calculate positions
  */
 
 /**
@@ -208,7 +211,7 @@
  * @property {Date} date - Date being displayed
  * @property {string} dayName - Localized day name
  * @property {boolean} isToday - Whether this is today
- * @property {import('./core/events/Event.js').Event[]} allDayEvents - All-day events
+ * @property {import('./events/Event.js').Event[]} allDayEvents - All-day events
  * @property {HourSlot[]} hours - Hourly time slots
  */
 
@@ -216,7 +219,7 @@
  * @typedef {Object} HourSlot
  * @property {number} hour - Hour (0-23)
  * @property {string} time - Formatted time string
- * @property {import('./core/events/Event.js').Event[]} events - Events in this hour
+ * @property {import('./events/Event.js').Event[]} events - Events in this hour
  */
 
 /**
@@ -233,7 +236,7 @@
  * @property {Date} date - Date object
  * @property {string} dayName - Localized day name
  * @property {boolean} isToday - Whether this is today
- * @property {import('./core/events/Event.js').Event[]} events - Events for this day
+ * @property {import('./events/Event.js').Event[]} events - Events for this day
  */
 
 /**
@@ -273,9 +276,9 @@
 /**
  * @typedef {Object} EventStoreChange
  * @property {('add'|'update'|'remove'|'clear')} type - Type of change
- * @property {import('./core/events/Event.js').Event} [event] - Affected event
- * @property {import('./core/events/Event.js').Event} [oldEvent] - Previous event state (for updates)
- * @property {import('./core/events/Event.js').Event[]} [oldEvents] - Previous events (for clear)
+ * @property {import('./events/Event.js').Event} [event] - Affected event
+ * @property {import('./events/Event.js').Event} [oldEvent] - Previous event state (for updates)
+ * @property {import('./events/Event.js').Event[]} [oldEvents] - Previous events (for clear)
  * @property {number} version - Store version number
  */
 
@@ -305,16 +308,16 @@
 
 /**
  * @typedef {Object} CalendarPlugin
- * @property {function(import('./core/calendar/Calendar.js').Calendar): void} install - Installation function
- * @property {function(import('./core/calendar/Calendar.js').Calendar): void} [uninstall] - Cleanup function
+ * @property {(calendar: import('./calendar/Calendar.js').Calendar) => void} install - Installation function
+ * @property {(calendar: import('./calendar/Calendar.js').Calendar) => void} [uninstall] - Cleanup function
  */
 
 /**
- * @typedef {function(any): void} EventListener
+ * @typedef {(payload: any) => void} EventListener
  */
 
 /**
- * @typedef {function(): void} UnsubscribeFn
+ * @typedef {() => void} UnsubscribeFn
  */
 
 /**

package/package.json

@@ -1,32 +1,55 @@
 {
   "name": "@forcecalendar/core",
-  "version": "2.1.70",
+  "version": "2.3.0",
   "type": "module",
   "private": false,
   "description": "A modern, lightweight, framework-agnostic calendar engine optimized for Salesforce",
   "main": "core/index.js",
   "module": "core/index.js",
-  "types": "core/types.js",
+  "types": "./types/index.d.ts",
   "sideEffects": false,
   "scripts": {
     "test": "node tests/run-all.js",
     "test:ics": "node tests/integration/test-ics.js",
     "test:search": "node tests/integration/test-search.js",
-    "lint": "eslint core/ --ext .js",
-    "lint:fix": "eslint core/ --ext .js --fix",
+    "lint": "eslint core/",
+    "lint:fix": "eslint core/ --fix",
     "format": "prettier --write \"core/**/*.js\"",
     "format:check": "prettier --check \"core/**/*.js\"",
     "quality": "npm run lint && npm run format:check",
-    "sync:version": "node scripts/sync-version.js"
+    "sync:version": "node scripts/sync-version.js",
+    "build:types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm run build:types"
   },
   "exports": {
-    ".": "./core/index.js",
-    "./calendar": "./core/calendar/Calendar.js",
-    "./events": "./core/events/Event.js",
-    "./state": "./core/state/StateManager.js",
-    "./search": "./core/search/EventSearch.js",
-    "./ics": "./core/ics/ICSHandler.js",
-    "./types": "./core/types.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./core/index.js"
+    },
+    "./calendar": {
+      "types": "./types/calendar/Calendar.d.ts",
+      "default": "./core/calendar/Calendar.js"
+    },
+    "./events": {
+      "types": "./types/events/Event.d.ts",
+      "default": "./core/events/Event.js"
+    },
+    "./state": {
+      "types": "./types/state/StateManager.d.ts",
+      "default": "./core/state/StateManager.js"
+    },
+    "./search": {
+      "types": "./types/search/EventSearch.d.ts",
+      "default": "./core/search/EventSearch.js"
+    },
+    "./ics": {
+      "types": "./types/ics/ICSHandler.d.ts",
+      "default": "./core/ics/ICSHandler.js"
+    },
+    "./types": {
+      "types": "./types/types.d.ts",
+      "default": "./core/types.js"
+    }
   },
   "repository": {
     "type": "git",
@@ -50,20 +73,17 @@
   },
   "homepage": "https://github.com/forceCalendar/core#readme",
   "devDependencies": {
-    "@babel/core": "^7.29.6",
-    "@babel/preset-env": "^7.29.7",
-    "@rollup/plugin-babel": "^7.0.0",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-terser": "^1.0.0",
-    "eslint": "^8.50.0",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.6.0",
+    "globals": "^17.7.0",
     "prettier": "^3.0.3",
-    "rollup": "^4.61.1",
-    "vite": "^6.4.3"
+    "typescript": "^7.0.2"
   },
   "files": [
     "core/**/*.js",
     "!core/**/*.test.js",
     "!core/**/*.spec.js",
+    "types/**/*.d.ts",
     "README.md",
     "LICENSE"
   ]

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;
+}