@forcecalendar/core 2.4.0 → 2.5.1

package/core/calendar/Calendar.js

@@ -178,9 +178,12 @@ export class Calendar {
 
   /**
    * Update an event
-   * @param {string} eventId - The event ID
+   *
+   * An occurrence id taken from view data (see {@link Event.occurrenceId})
+   * updates the recurring master, i.e. the whole series.
+   * @param {string} eventId - Event id or occurrence id
    * @param {Object} updates - Properties to update
-   * @returns {Event} The updated event
+   * @returns {Event} The updated event (the master for an occurrence id)
    */
   updateEvent(eventId, updates) {
     const oldEvent = this.eventStore.getEvent(eventId);
@@ -193,7 +196,10 @@ export class Calendar {
 
   /**
    * Remove an event
-   * @param {string} eventId - The event ID
+   *
+   * An occurrence id taken from view data (see {@link Event.occurrenceId})
+   * removes the recurring master, i.e. the whole series.
+   * @param {string} eventId - Event id or occurrence id
    * @returns {boolean} True if removed
    */
   removeEvent(eventId) {
@@ -218,15 +224,48 @@ export class Calendar {
 
   /**
    * Get an event by ID
-   * @param {string} eventId - The event ID
-   * @returns {Event|null}
+   *
+   * Occurrence ids taken from view data (`<masterId>_<startMs>`, see
+   * {@link Event.occurrenceId}) resolve to the stored recurring master, so
+   * every id a renderer hands back can be looked up here.
+   * @param {string} eventId - Event id or occurrence id
+   * @returns {Event|null} The stored event (the master for an occurrence id) or null
    */
   getEvent(eventId) {
     return this.eventStore.getEvent(eventId);
   }
 
   /**
-   * Get all events
+   * Resolve an event id or occurrence id to the id of the stored event it
+   * refers to: the id itself for a stored event, the master's id for an
+   * occurrence id taken from view data, `null` when nothing stored matches.
+   * See `EventStore.resolveEventId`.
+   *
+   * @example
+   * calendar.resolveEventId('standup_1750028400000'); // 'standup'
+   * calendar.resolveEventId('unknown'); // null
+   *
+   * @param {string} id - Event id or occurrence id
+   * @returns {string|null} Id of the stored event, or null
+   */
+  resolveEventId(id) {
+    return this.eventStore.resolveEventId(id);
+  }
+
+  /**
+   * Get the occurrence an occurrence id from view data stands for, as an
+   * {@link Event} like the ones the views hold, or `null` when the id is
+   * not an occurrence of a stored recurring series. See
+   * `EventStore.getOccurrence`.
+   * @param {string} occurrenceId - Occurrence id (`<masterId>_<startMs>`)
+   * @returns {Event|null} The occurrence, or null
+   */
+  getOccurrence(occurrenceId) {
+    return this.eventStore.getOccurrence(occurrenceId, this.config.timeZone);
+  }
+
+  /**
+   * Get all stored events (recurring masters, never their occurrences)
    * @returns {Event[]}
    */
   getEvents() {
@@ -259,13 +298,14 @@ export class Calendar {
     if (options.reconcile) {
       return this.reconcileEvents(events, options);
     }
+    this._assertIterable(events, 'setEvents');
 
     const removed = this.getEvents();
     this.eventStore.loadEvents(events);
     const added = this.getEvents();
 
     /** @type {import('../types.js').EventsSetPayload} */
-    const payload = { events: added, added, updated: [], removed, unchanged: [] };
+    const payload = { events: this.getEvents(), added, updated: [], removed, unchanged: [] };
     this._emit('eventsSet', payload);
     return payload;
   }
@@ -295,9 +335,10 @@ export class Calendar {
    * @param {Array<import('../events/Event.js').Event|import('../types.js').EventData>} events - Complete snapshot of events
    * @param {import('../types.js').ReconcileOptions} [options={}] - Reconcile options
    * @returns {import('../types.js').EventsSetPayload} Resulting events and the applied change set
-   * @throws {Error} If an entry fails validation or two entries share an id
+   * @throws {Error} If `events` is not iterable, an entry fails validation or two entries share an id
    */
   reconcileEvents(events, options = {}) {
+    this._assertIterable(events, 'reconcileEvents');
     const { removeMissing, isEquivalent } = options;
     const prepared = [];
     for (const eventData of events) {
@@ -320,6 +361,18 @@ export class Calendar {
     return payload;
   }
 
+  /**
+   * Throw a clear error when a snapshot is not iterable
+   * @param {*} events - Candidate snapshot
+   * @param {string} method - Calling method, for the message
+   * @private
+   */
+  _assertIterable(events, method) {
+    if (!events || typeof events[Symbol.iterator] !== 'function') {
+      throw new Error(`${method}() expects an iterable of events`);
+    }
+  }
+
   /**
    * Get the event store's change counter
    *
@@ -344,7 +397,7 @@ export class Calendar {
   }
 
   /**
-   * Get events for a specific date
+   * Get events for a specific date, with recurring series expanded into occurrences
    * @param {Date} date - The date
    * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
    * @returns {Event[]}
@@ -353,6 +406,20 @@ export class Calendar {
     return this.eventStore.getEventsForDate(date, timezone || this.config.timeZone);
   }
 
+  /**
+   * Get the events for every day in a range, keyed by local date (YYYY-MM-DD)
+   *
+   * Recurring series are expanded once for the whole range; this is what the
+   * month and week views use. See `EventStore.getEventsByDate`.
+   * @param {Date} start - First day of the range
+   * @param {Date} end - Last day of the range
+   * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
+   * @returns {Map<string, Event[]>} Local date string -> events on that day
+   */
+  getEventsByDate(start, end, timezone = null) {
+    return this.eventStore.getEventsByDate(start, end, timezone || this.config.timeZone);
+  }
+
   /**
    * Get events in a date range
    * @param {Date} start - Start date
@@ -364,6 +431,64 @@ export class Calendar {
     return this.eventStore.getEventsInRange(start, end, true, timezone || this.config.timeZone);
   }
 
+  /**
+   * Lazily iterate the occurrences of an event in chronological order.
+   *
+   * Occurrences are produced one at a time, so taking the next few of an
+   * open-ended series does not expand the series. `after` and `before`
+   * are exclusive unless `inclusive` is set; see
+   * RecurrenceEngineV2.iterateOccurrences for the full semantics.
+   *
+   * @example
+   * for (const occurrence of calendar.iterateOccurrences('standup', { after: new Date() })) {
+   *   if (occurrence.start > deadline) break;
+   *   remind(occurrence);
+   * }
+   *
+   * @param {string} eventId - Event id or occurrence id (resolved to its master)
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+   * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>} Occurrences in chronological order
+   * @throws {Error} If no event with the ID exists
+   */
+  iterateOccurrences(eventId, options = {}) {
+    return this.eventStore.iterateOccurrences(eventId, options);
+  }
+
+  /**
+   * First occurrence of an event after an instant, or null when the
+   * series has no occurrence after it. `after` is exclusive unless
+   * `options.inclusive` is set.
+   *
+   * @example
+   * const upcoming = calendar.getNextOccurrence('standup', new Date());
+   *
+   * @param {string} eventId - Event id or occurrence id (resolved to its master)
+   * @param {Date|number} [after=null] - Instant to search from (defaults to the series start)
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Further options
+   * @returns {import('../types.js').ExpandedOccurrence|null} The next occurrence, or null
+   * @throws {Error} If no event with the ID exists
+   */
+  getNextOccurrence(eventId, after = null, options = {}) {
+    return this.eventStore.getNextOccurrence(eventId, after, options);
+  }
+
+  /**
+   * The first `count` occurrences of an event inside a window, generated
+   * lazily. `count` is capped at the engine's MAX_OCCURRENCES_HARD_LIMIT.
+   *
+   * @example
+   * const nextFive = calendar.takeOccurrences('standup', 5, { after: new Date() });
+   *
+   * @param {string} eventId - Event id or occurrence id (resolved to its master)
+   * @param {number} count - Maximum number of occurrences to return (fractions are floored)
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+   * @returns {import('../types.js').ExpandedOccurrence[]} Up to `count` occurrences in chronological order
+   * @throws {Error} If no event with the ID exists
+   */
+  takeOccurrences(eventId, count, options = {}) {
+    return this.eventStore.takeOccurrences(eventId, count, options);
+  }
+
   /**
    * Set the calendar's timezone
    * @param {string} timezone - IANA timezone identifier
@@ -529,6 +654,12 @@ export class Calendar {
       ? 6
       : Math.ceil((lastDay.getDate() + DateUtils.getDayOfWeek(firstDay, weekStartsOn)) / 7);
 
+    // Expand recurring series once for the whole grid, not once per cell
+    const eventsByDate = this.getEventsByDate(
+      startDate,
+      DateUtils.addDays(startDate, maxWeeks * 7 - 1)
+    );
+
     for (let weekIndex = 0; weekIndex < maxWeeks; weekIndex++) {
       const week = {
         weekNumber: DateUtils.getWeekNumber(currentDate),
@@ -547,7 +678,7 @@ export class Calendar {
           isCurrentMonth,
           isToday,
           isWeekend,
-          events: this.getEventsForDate(dayDate)
+          events: eventsByDate.get(DateUtils.getLocalDateString(dayDate)) || []
         });
 
         // Use DateUtils.addDays to handle month boundaries correctly
@@ -580,8 +711,12 @@ export class Calendar {
     const days = [];
     const currentDate = new Date(startDate);
 
+    // Expand recurring series once for the whole week, not once per day
+    const eventsByDate = this.getEventsByDate(startDate, endDate);
+
     for (let i = 0; i < 7; i++) {
       const dayDate = new Date(currentDate);
+      const events = eventsByDate.get(DateUtils.getLocalDateString(dayDate)) || [];
       days.push({
         date: dayDate,
         dayOfMonth: dayDate.getDate(),
@@ -589,9 +724,9 @@ export class Calendar {
         dayName: DateUtils.getDayName(dayDate, this.state.get('locale')),
         isToday: DateUtils.isToday(dayDate),
         isWeekend: dayDate.getDay() === 0 || dayDate.getDay() === 6,
-        events: this.getEventsForDate(dayDate),
+        events,
         // Add overlap groups for positioning overlapping events
-        overlapGroups: this.eventStore.getOverlapGroups(dayDate, true),
+        overlapGroups: this.eventStore.groupOverlappingEvents(events, true),
         getEventPositions: events => this.eventStore.calculateEventPositions(events)
       });
       // Move to next day
@@ -612,11 +747,19 @@ export class Calendar {
    * @private
    */
   _getDayViewData(date) {
+    const timezone = this.config.timeZone;
     const events = this.getEventsForDate(date);
 
-    // Separate all-day and timed events
+    // Separate all-day and timed events. Hour slots are placed on the
+    // calendar's wall clock, so timed events are compared in that timezone.
     const allDayEvents = events.filter(e => e.allDay);
-    const timedEvents = events.filter(e => !e.allDay);
+    const timedEvents = events
+      .filter(e => !e.allDay)
+      .map(event => ({
+        event,
+        start: event.getStartInTimezone(timezone),
+        end: event.getEndInTimezone(timezone)
+      }));
 
     // Create hourly slots for timed events
     const hours = [];
@@ -629,11 +772,13 @@ export class Calendar {
       hours.push({
         hour,
         time: DateUtils.formatTime(hourDate, this.state.get('locale')),
-        events: timedEvents.filter(event => {
-          // Check if event occurs during this hour (not just starts)
-          // Event occurs in this hour if it overlaps with the hour slot
-          return event.start < hourEnd && event.end > hourDate;
-        })
+        events: timedEvents
+          .filter(({ start, end }) => {
+            // Check if event occurs during this hour (not just starts)
+            // Event occurs in this hour if it overlaps with the hour slot
+            return start < hourEnd && end > hourDate;
+          })
+          .map(({ event }) => event)
       });
     }
 
@@ -695,14 +840,37 @@ export class Calendar {
 
   /**
    * Select an event
-   * @param {string} eventId - Event ID to select
+   *
+   * Accepts a stored event's id or an occurrence id taken from view data
+   * (see {@link Event.occurrenceId}). Either way the stored event is what
+   * gets selected: `selectedEventId` in the state holds its id, so it can
+   * always be looked up with {@link Calendar#getEvent}. The `eventSelect`
+   * payload carries the stored `event`, its `eventId`, and for an
+   * occurrence id also `occurrenceId` and the `occurrence` itself (an
+   * {@link Event} as in view data, or null when the series has no
+   * occurrence at that instant). Nothing happens for an unknown id.
+   *
+   * @example
+   * calendar.on('eventSelect', ({ event, occurrence }) => open(occurrence || event));
+   * calendar.selectEvent(chip.dataset.eventId);
+   *
+   * @param {string} eventId - Event id or occurrence id to select
    */
   selectEvent(eventId) {
     const event = this.getEvent(eventId);
-    if (event) {
-      this.state.selectEvent(eventId);
-      this._emit('eventSelect', { event });
+    if (!event) {
+      return;
     }
+    const isOccurrence = eventId !== event.id;
+    this.state.selectEvent(event.id);
+    /** @type {import('../types.js').EventSelectPayload} */
+    const payload = {
+      event,
+      eventId: event.id,
+      occurrenceId: isOccurrence ? eventId : null,
+      occurrence: isOccurrence ? this.getOccurrence(eventId) : null
+    };
+    this._emit('eventSelect', payload);
   }
 
   /**

package/core/events/Event.js

@@ -42,6 +42,33 @@ function deepEqual(a, b) {
   return true;
 }
 
+/**
+ * Timezone identifiers Intl has already accepted. Every Event construction
+ * (each clone, each occurrence of a recurring series) validates its
+ * timezone, and constructing an Intl.DateTimeFormat per event dominated
+ * the cost of expanding a month grid.
+ * @type {Set<string>}
+ */
+const validatedTimezones = new Set();
+
+/**
+ * Throw unless Intl accepts the timezone identifier
+ * @param {string} timezone - IANA timezone identifier
+ * @param {string} label - Field name for the error message
+ * @throws {Error} If the timezone is not valid
+ */
+function assertValidTimezone(timezone, label) {
+  if (validatedTimezones.has(timezone)) {
+    return;
+  }
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+  } catch (e) {
+    throw new Error(`Invalid ${label}: ${timezone}`, { cause: e });
+  }
+  validatedTimezones.add(timezone);
+}
+
 export class Event {
   // Field size limits
   static FIELD_LIMITS = {
@@ -204,22 +231,12 @@ export class Event {
       });
     }
 
-    // Validate timezone if provided
+    // Validate timezones if provided (memoised per identifier)
     if (data.timeZone) {
-      try {
-        new Intl.DateTimeFormat('en-US', { timeZone: data.timeZone });
-      } catch (e) {
-        throw new Error(`Invalid timezone: ${data.timeZone}`, { cause: e });
-      }
+      assertValidTimezone(data.timeZone, 'timezone');
     }
-
-    // Validate end timezone if provided
     if (data.endTimeZone) {
-      try {
-        new Intl.DateTimeFormat('en-US', { timeZone: data.endTimeZone });
-      } catch (e) {
-        throw new Error(`Invalid end timezone: ${data.endTimeZone}`, { cause: e });
-      }
+      assertValidTimezone(data.endTimeZone, 'end timezone');
     }
   }
 
@@ -325,6 +342,16 @@ export class Event {
     this.recurring = normalized.recurring;
     this.recurrenceRule = normalized.recurrenceRule;
 
+    // Occurrence identity. Set by EventStore.expandRecurringEvent on the
+    // instances it derives from a recurring series; stored events keep the
+    // defaults. The id of an occurrence is Event.occurrenceId(master, start).
+    /** @type {boolean} True when this instance is one occurrence of a recurring series */
+    this.isOccurrence = false;
+    /** @type {string|null} Id of the recurring master this occurrence belongs to */
+    this.recurringEventId = null;
+    /** @type {Date|null} Start of this occurrence as generated by the recurrence rule */
+    this.occurrenceStart = null;
+
     // Store original timezone from system if not provided
     this._originalTimeZone = normalized.timeZone || null;
 
@@ -650,6 +677,8 @@ export class Event {
    * Scalars are compared with strict equality, dates by timestamp and
    * structured fields (recurrence rule, organizer, attendees, reminders,
    * categories, attachments, conference data, metadata) structurally.
+   * The `color` shorthand is not listed: normalization copies it into
+   * `backgroundColor` and `borderColor`, which are compared instead.
    * @type {ReadonlyArray<string>}
    */
   static EQUIVALENCE_FIELDS = Object.freeze([
@@ -662,7 +691,6 @@ export class Event {
     'endTimeZone',
     'description',
     'location',
-    'color',
     'backgroundColor',
     'borderColor',
     'textColor',
@@ -694,6 +722,14 @@ export class Event {
    * describe the same event. Two events with different ids are never
    * equivalent.
    *
+   * Two things to know when building snapshots for `reconcile()`:
+   * - `attendees`, `reminders`, `categories` and `attachments` are compared
+   *   in order, so the same attendees listed in a different order count as
+   *   a change.
+   * - Only the top-level dates are normalized. Values inside `metadata` are
+   *   compared as given, so a `Date` and its ISO string are not equivalent
+   *   there; keep metadata in one representation.
+   *
    * This is the default comparator used by `EventStore.reconcile()` to decide
    * whether an incoming snapshot entry replaces the stored event.
    *
@@ -721,6 +757,62 @@ export class Event {
     return true;
   }
 
+  /**
+   * Build the id of one occurrence of a recurring series.
+   *
+   * The id is `<recurringEventId>_<startMs>` where `startMs` is the
+   * occurrence start as returned by `Date.prototype.getTime()`. It is
+   * deterministic, so the same occurrence gets the same id no matter which
+   * range it was expanded for, and it matches the ids generated by
+   * `RecurrenceEngineV2`. Use {@link Event.parseOccurrenceId} to get the
+   * master id back.
+   *
+   * @example
+   * Event.occurrenceId('standup', new Date(2025, 5, 16, 9)); // 'standup_1750028400000'
+   *
+   * @param {string} recurringEventId - Id of the recurring master event
+   * @param {Date|number|string} occurrenceStart - Start of the occurrence
+   * @returns {string} Occurrence id
+   * @throws {TypeError} If occurrenceStart is not a valid date
+   */
+  static occurrenceId(recurringEventId, occurrenceStart) {
+    const start = occurrenceStart instanceof Date ? occurrenceStart : new Date(occurrenceStart);
+    const startMs = start.getTime();
+    if (Number.isNaN(startMs)) {
+      throw new TypeError('Event.occurrenceId: occurrenceStart must be a valid Date or timestamp');
+    }
+    return `${recurringEventId}_${startMs}`;
+  }
+
+  /**
+   * Split an occurrence id built by {@link Event.occurrenceId} into the master
+   * id and the occurrence start.
+   *
+   * Returns `null` for ids that do not have the `<id>_<startMs>` shape. A
+   * positive result only means the id is well-formed; whether the master
+   * exists is for the caller (see `EventStore.getEvent`) to check.
+   *
+   * @param {string} id - Candidate occurrence id
+   * @returns {{recurringEventId: string, occurrenceStart: Date}|null} Parsed parts or null
+   */
+  static parseOccurrenceId(id) {
+    if (typeof id !== 'string') {
+      return null;
+    }
+    const separator = id.lastIndexOf('_');
+    if (separator <= 0 || separator === id.length - 1) {
+      return null;
+    }
+    const time = id.slice(separator + 1);
+    if (!/^-?\d+$/.test(time)) {
+      return null;
+    }
+    return {
+      recurringEventId: id.slice(0, separator),
+      occurrenceStart: new Date(Number(time))
+    };
+  }
+
   // ============ Attendee Management Methods ============
 
   /**