@forcecalendar/core 2.5.0 → 2.5.1

package/core/types.js

@@ -324,6 +324,15 @@
  * @property {import('./events/Event.js').Event[]} unchanged - Events left untouched
  */
 
+/**
+ * Payload of the Calendar `eventSelect` event
+ * @typedef {Object} EventSelectPayload
+ * @property {import('./events/Event.js').Event} event - The stored event (the master for an occurrence id)
+ * @property {string} eventId - Id of the stored event, as kept in the state's selectedEventId
+ * @property {string|null} occurrenceId - The occurrence id that was selected, or null for a stored event's id
+ * @property {import('./events/Event.js').Event|null} occurrence - The selected occurrence as in view data, or null
+ */
+
 /**
  * @typedef {Object} QueryFilters
  * @property {Date} [start] - Start date for range query

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forcecalendar/core",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "type": "module",
   "private": false,
   "description": "A modern, lightweight, framework-agnostic calendar engine optimized for Salesforce",

package/types/calendar/Calendar.d.ts

@@ -113,6 +113,29 @@ export declare class Calendar {
      * @returns {Event|null} The stored event (the master for an occurrence id) or null
      */
     getEvent(eventId: string): Event | null;
+    /**
+     * 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: string): string | null;
+    /**
+     * 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: string): Event | null;
     /**
      * Get all stored events (recurring masters, never their occurrences)
      * @returns {Event[]}
@@ -166,9 +189,16 @@ export declare 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: Array<import('../events/Event.js').Event | import('../types.js').EventData>, options?: import('../types.js').ReconcileOptions): import('../types.js').EventsSetPayload;
+    /**
+     * Throw a clear error when a snapshot is not iterable
+     * @param {*} events - Candidate snapshot
+     * @param {string} method - Calling method, for the message
+     * @private
+     */
+    private _assertIterable;
     /**
      * Get the event store's change counter
      *
@@ -226,7 +256,7 @@ export declare class Calendar {
      *   remind(occurrence);
      * }
      *
-     * @param {string} eventId - The event ID
+     * @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
@@ -240,7 +270,7 @@ export declare class Calendar {
      * @example
      * const upcoming = calendar.getNextOccurrence('standup', new Date());
      *
-     * @param {string} eventId - The event ID
+     * @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
@@ -254,8 +284,8 @@ export declare class Calendar {
      * @example
      * const nextFive = calendar.takeOccurrences('standup', 5, { after: new Date() });
      *
-     * @param {string} eventId - The event ID
-     * @param {number} count - Maximum number of occurrences to return
+     * @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
@@ -363,7 +393,21 @@ export declare class Calendar {
     private _getListViewData;
     /**
      * 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: string): void;
     /**

package/types/events/Event.d.ts

@@ -167,6 +167,8 @@ export declare 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: ReadonlyArray<string>;
@@ -185,6 +187,14 @@ export declare 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.
      *
@@ -214,6 +224,7 @@ export declare class Event {
      * @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: string, occurrenceStart: Date | number | string): string;
     /**

package/types/events/EventStore.d.ts

@@ -96,6 +96,14 @@ export declare class EventStore {
      * @private
      */
     private _detachEvent;
+    /**
+     * Drop the recurrence engine's cached expansions of one series, or of
+     * every series when no id is given. The engine is pluggable, so both
+     * hooks are optional.
+     * @param {string} [eventId] - Series to invalidate; omit to clear everything
+     * @private
+     */
+    private _invalidateOccurrenceCache;
     /**
      * Get an event by ID
      *
@@ -115,6 +123,40 @@ export declare class EventStore {
      * @private
      */
     private _resolveOccurrenceMaster;
+    /**
+     * Resolve an id taken from anywhere (store, view data, a drag or click
+     * handler) to the id of the stored event it refers to.
+     *
+     * Returns the id itself for a stored event, the master's id for an
+     * occurrence id (see {@link Event.occurrenceId}) whose master is a stored
+     * recurring event, and `null` when nothing stored matches. This is the
+     * same resolution {@link EventStore#getEvent}, updateEvent and removeEvent
+     * apply, exposed for consumers that only need the id.
+     *
+     * @example
+     * const masterId = store.resolveEventId(chip.dataset.eventId); // 'standup' for 'standup_1750028400000'
+     *
+     * @param {string} id - Event id or occurrence id
+     * @returns {string|null} Id of the stored event, or null
+     */
+    resolveEventId(id: string): string | null;
+    /**
+     * Get the occurrence an occurrence id stands for, as an {@link Event}
+     * exactly like the ones {@link EventStore#expandRecurringEvent} returns.
+     *
+     * Returns `null` when the id is not an occurrence id, its master is not a
+     * stored recurring event, or the series has no occurrence starting at the
+     * encoded instant. A master id is never an occurrence, so it yields null
+     * too; use {@link EventStore#getEvent} for the master.
+     *
+     * @example
+     * const occurrence = store.getOccurrence('standup_1750028400000');
+     *
+     * @param {string} occurrenceId - Occurrence id (`<masterId>_<startMs>`)
+     * @param {string} [timezone] - Timezone for the expansion (defaults to the store timezone)
+     * @returns {Event|null} The occurrence, or null
+     */
+    getOccurrence(occurrenceId: string, timezone?: string): Event | null;
     /**
      * Get all events
      * @returns {Event[]} Array of all events
@@ -278,7 +320,7 @@ export declare class EventStore {
      *   remind(occurrence);
      * }
      *
-     * @param {string} eventId - The event ID
+     * @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
@@ -292,7 +334,7 @@ export declare class EventStore {
      * @example
      * const upcoming = store.getNextOccurrence('standup', new Date());
      *
-     * @param {string} eventId - The event ID
+     * @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
@@ -307,8 +349,8 @@ export declare class EventStore {
      * @example
      * const nextFive = store.takeOccurrences('standup', 5, { after: new Date() });
      *
-     * @param {string} eventId - The event ID
-     * @param {number} count - Maximum number of occurrences to return
+     * @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
@@ -343,13 +385,23 @@ export declare class EventStore {
      * - adds events whose id is not in the store (`add` change),
      * - removes stored events missing from the snapshot (`remove` change),
      *   unless `removeMissing` is `false`,
+     * - treats occurrences of a recurring series (entries with
+     *   `isOccurrence: true`, the plain object of such an occurrence, or an id
+     *   that {@link EventStore#getEvent} resolves to a stored recurring master)
+     *   as a reference to their master: the master is kept as unchanged and is
+     *   never replaced by an occurrence. An occurrence whose master is neither
+     *   stored nor in the snapshot is an error,
      * - emits a single `batch` notification listing those changes, or nothing at
      *   all when the snapshot matches the store. When called while a batch is
      *   already open the changes are queued on that batch instead.
      *
-     * Input is validated up front: invalid event data or duplicate ids throw
-     * before the store is modified. Any error raised while applying the diff
-     * rolls the store back to its previous state.
+     * Input is validated up front: invalid event data, duplicate ids and
+     * occurrences without a master throw before the store is modified. When
+     * reconcile opens the batch itself, any error raised while applying the
+     * diff rolls the store back to its previous state; inside a batch opened
+     * by the caller the changes applied so far stay queued on that batch, and
+     * it is the caller's rollbackBatch() that undoes them (a custom
+     * `isEquivalent` that throws is the usual way to get there).
      *
      * @example
      * // periodic server snapshot
@@ -362,6 +414,16 @@ export declare class EventStore {
      * @throws {Error} If an entry fails validation or two entries share an id
      */
     reconcile(events: Array<Event | import('../types.js').EventData>, options?: import('../types.js').ReconcileOptions): import('../types.js').ReconcileResult;
+    /**
+     * Id of the recurring master a reconcile entry is an occurrence of, or
+     * null when the entry is an event in its own right. Recognises Event
+     * occurrences (isOccurrence), their toObject() form (occurrence markers
+     * in metadata) and ids that resolve to a stored recurring master.
+     * @param {Event|import('../types.js').EventData} eventData - Reconcile entry
+     * @returns {string|null} Master id or null
+     * @private
+     */
+    private _occurrenceMasterId;
     /**
      * Subscribe to store changes
      * @param {Function} callback - Callback function
@@ -399,16 +461,18 @@ export declare class EventStore {
      */
     private _removeFromReferencedIndex;
     /**
-     * Notify listeners of changes
+     * Deliver a change now, or queue it when a batch is open
+     * @param {import('../types.js').EventStoreChange} change - Change to deliver
      * @private
      */
+    private _queueChange;
     /**
-     * Deliver a change now, or queue it when a batch is open
+     * Deliver a change to every subscriber now, regardless of batch mode.
+     * A listener that throws is reported and does not stop the others.
      * @param {import('../types.js').EventStoreChange} change - Change to deliver
      * @private
      */
-    private _queueChange;
-    _notifyChange(change: any): void;
+    private _notifyChange;
     /**
      * Get store statistics
      * @returns {Object}
@@ -466,7 +530,7 @@ export declare class EventStore {
      */
     getPerformanceMetrics(): Object;
     /**
-     * Clear all caches
+     * Clear all caches, including the recurrence engine's cached expansions
      */
     clearCaches(): void;
     /**

package/types/events/RRuleParser.d.ts

@@ -36,7 +36,16 @@ export declare class RRuleParser {
      */
     private static parseExceptionDates;
     /**
-     * Validate and normalize rule
+     * Validate and normalize a rule.
+     *
+     * Works on a copy: rule objects handed in are typically the stored
+     * recurrenceRule of an Event, and normalising them in place would make
+     * the stored event differ from the data it was created from (a spurious
+     * update on the next reconcile) and let the engines' per-rule caches leak
+     * into it. The copy is shallow except for the array fields, which are
+     * copied as well.
+     * @param {Object} rule - Rule object (not modified)
+     * @returns {Object} Normalised copy
      * @private
      */
     private static validateRule;

package/types/events/RecurrenceEngine.d.ts

@@ -94,7 +94,7 @@ export declare class RecurrenceEngine {
      * const nextFive = RecurrenceEngine.takeOccurrences(event, 5, { after: new Date() });
      *
      * @param {import('./Event.js').Event} event - The event to query
-     * @param {number} count - Maximum number of occurrences to return
+     * @param {number} count - Maximum number of occurrences to return (fractions are floored)
      * @param {import('../types.js').OccurrenceIteratorOptions} [options={}] - Window and timezone
      * @returns {import('../types.js').EventOccurrence[]} Up to `count` occurrences in chronological order
      */
@@ -239,7 +239,9 @@ export declare class RecurrenceEngine {
     private static _seekWeekCycle;
     /**
      * Find the next system-timezone offset transition after fromMs.
-     * Cached module-wide: the system timezone is fixed for the process.
+     * Cached module-wide: the system timezone is fixed for the process. The
+     * cache grows incrementally, so extending coverage (a view navigating
+     * forward, a series with a far-past DTSTART) scans only the new span.
      * @param {number} fromMs - Search from this timestamp (exclusive)
      * @param {number} toMs - Extend cache coverage at least this far
      * @returns {number} Transition timestamp, or Infinity if none within coverage

package/types/events/RecurrenceEngineV2.d.ts

@@ -15,10 +15,15 @@ export declare class RecurrenceEngineV2 {
     /**
      * Expand recurring event with advanced handling
      *
-     * Occurrences before rangeStart are skipped without being generated:
-     * daily, weekly, hourly and minutely rules seek straight to the range, so
-     * a series that started years before the queried window is expanded at
-     * the same cost as one that started yesterday.
+     * Occurrences before rangeStart are skipped without being generated for
+     * the rules seekToRange can seek: DAILY (without BYHOUR), WEEKLY (with or
+     * without BYDAY), HOURLY and MINUTELY. Such a series that started years
+     * before the queried window is expanded at the same cost as one that
+     * started yesterday. MONTHLY and YEARLY rules, and DAILY with BYHOUR,
+     * are stepped from DTSTART; they take few enough steps per year that
+     * this is cheap, but an expansion that would need more than
+     * MAX_ITERATIONS_HARD_LIMIT steps is truncated (with one console.warn
+     * per process).
      *
      * @param {import('./Event.js').Event} event - Recurring event
      * @param {Date} rangeStart - Start of expansion range
@@ -46,7 +51,7 @@ export declare class RecurrenceEngineV2 {
      * time and without the expansion cache: stored instance modifications
      * and exceptions are applied as each occurrence is produced, so changes
      * made through addModifiedInstance or addException are visible on the
-     * next pull. Rules seekToRange can seek (plain daily and weekly, hourly,
+     * next pull. Rules seekToRange can seek (daily, weekly, hourly,
      * minutely) jump straight to `after`, and DST transitions are scanned
      * lazily ahead of the cursor instead of for the whole window up front.
      *
@@ -98,7 +103,7 @@ export declare class RecurrenceEngineV2 {
      * const nextFive = engine.takeOccurrences(event, 5, { after: new Date() });
      *
      * @param {import('./Event.js').Event} event - The event to query
-     * @param {number} count - Maximum number of occurrences to return
+     * @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
      */
@@ -136,8 +141,9 @@ export declare class RecurrenceEngineV2 {
      * without stepping through every occurrence in between.
      *
      * Applies to rules whose step is a fixed duration between system-timezone
-     * transitions (plain DAILY and WEEKLY, HOURLY, MINUTELY); the step that
-     * crosses a transition is taken with getNextDate so the result is exactly
+     * transitions (plain DAILY and WEEKLY, HOURLY, MINUTELY) and to WEEKLY
+     * rules with BYDAY, whose steps repeat in a weekly cycle; the steps that
+     * cross a transition are taken with getNextDate so the result is exactly
      * what stepping from DTSTART would produce. Never seeks past UNTIL, and
      * counts skipped steps against COUNT.
      *
@@ -148,6 +154,40 @@ export declare class RecurrenceEngineV2 {
      * @param {string} timezone - Expansion timezone
      */
     seekToRange(state: Object, rule: Object, rangeStart: Date, rangeEnd: Date, timezone: string): void;
+    /**
+     * Seek for WEEKLY rules with BYDAY. getNextWeekly picks the next weekday
+     * from the BYDAY list (in list order), so the step from each weekday is
+     * fixed and the walk from DTSTART settles into a cycle of weekdays that
+     * repeats every whole number of weeks. The cursor is stepped one
+     * occurrence at a time until it is on that cycle (at most six steps),
+     * then whole cycles are skipped arithmetically between system-timezone
+     * transitions, exactly as seekToRange does for fixed steps.
+     * @param {Object} state - Expansion state (currentDate and count are updated)
+     * @param {Object} rule - Parsed recurrence rule
+     * @param {Date} rangeStart - Start of expansion range
+     * @param {Date} rangeEnd - End of expansion range
+     * @param {string} timezone - Expansion timezone
+     * @private
+     */
+    private _seekWeekCycle;
+    /**
+     * Days getNextWeekly adds from each weekday (index 0-6) for a WEEKLY
+     * rule with BYDAY, or null when the rule cannot be seeked (an invalid
+     * interval or day code, which the expansion loop handles as before)
+     * @param {Object} rule - Parsed recurrence rule
+     * @returns {number[]|null} Delta table indexed by Date#getDay()
+     * @private
+     */
+    private _weekdayDeltas;
+    /**
+     * Weekday numbers (Date#getDay) of a rule's BYDAY entries in ascending
+     * order, computed once per parsed rule. Invalid day codes map to
+     * undefined and sort last.
+     * @param {Object} rule - Parsed recurrence rule with byDay
+     * @returns {number[]} Sorted weekday numbers
+     * @private
+     */
+    private _weekdayTargets;
     /**
      * Milliseconds per step for rules getNextDate advances by a fixed
      * duration while the system UTC offset is constant
@@ -248,8 +288,27 @@ export declare class RecurrenceEngineV2 {
     getDateKey(date: any): string;
     /**
      * Create cache key
+     *
+     * When given the event itself the key also covers everything the
+     * expansion depends on (DTSTART, end, recurrence rule), so a series that
+     * is updated, replaced or re-added under the same id can never be served
+     * a stale expansion. Keys always start with `<eventId>_`, which is what
+     * {@link RecurrenceEngineV2#clearEventCache} matches on.
+     * @param {import('./Event.js').Event|string} event - Recurring event, or just its id
+     * @param {Date} start - Start of expansion range
+     * @param {Date} end - End of expansion range
+     * @param {Object} options - Expansion options
+     * @returns {string} Cache key
+     */
+    getCacheKey(event: import('./Event.js').Event | string, start: Date, end: Date, options: Object): string;
+    /**
+     * Stable text form of a recurrence rule for cache keys. A rule that
+     * cannot be serialised gets a unique fingerprint, i.e. is never cached.
+     * @param {string|Object} rule - RRULE string or rule object
+     * @returns {string} Fingerprint
+     * @private
      */
-    getCacheKey(eventId: any, start: any, end: any, options: any): string;
+    private _ruleFingerprint;
     /**
      * Cache occurrences
      */

package/types/index.d.ts

@@ -18,5 +18,5 @@ export { RRuleParser } from './events/RRuleParser.js';
 export { TimezoneManager } from './timezone/TimezoneManager.js';
 export { ConflictDetector } from './conflicts/ConflictDetector.js';
 export { EnhancedCalendar } from './integration/EnhancedCalendar.js';
-export declare const VERSION = "2.5.0";
+export declare const VERSION = "2.5.1";
 export { Calendar as default } from './calendar/Calendar.js';

package/types/integration/EnhancedCalendar.d.ts

@@ -13,8 +13,15 @@ export declare class EnhancedCalendar extends Calendar {
         expansionTime: never[];
         renderTime: never[];
     };
+    _unsubscribeCacheInvalidation: Function;
     _clearReindexTimeout: (() => void) | null | undefined;
     constructor(config: any);
+    /**
+     * Invalidate the enhanced engine's cached expansions for a store change
+     * @param {import('../types.js').EventStoreChange} change - Store change
+     * @private
+     */
+    private _invalidateOccurrenceCache;
     /**
      * Enhanced search with worker support
      */

package/types/types.d.ts

@@ -789,6 +789,24 @@ export type EventsSetPayload = {
      */
     unchanged: import('./events/Event.js').Event[];
 };
+export type EventSelectPayload = {
+    /**
+     * - The stored event (the master for an occurrence id)
+     */
+    event: import('./events/Event.js').Event;
+    /**
+     * - Id of the stored event, as kept in the state's selectedEventId
+     */
+    eventId: string;
+    /**
+     * - The occurrence id that was selected, or null for a stored event's id
+     */
+    occurrenceId: string | null;
+    /**
+     * - The selected occurrence as in view data, or null
+     */
+    occurrence: import('./events/Event.js').Event | null;
+};
 export type QueryFilters = {
     /**
      * - Start date for range query
@@ -1393,6 +1411,14 @@ export type ConflictSummary = {
  * @property {import('./events/Event.js').Event[]} removed - Events removed by the operation
  * @property {import('./events/Event.js').Event[]} unchanged - Events left untouched
  */
+/**
+ * Payload of the Calendar `eventSelect` event
+ * @typedef {Object} EventSelectPayload
+ * @property {import('./events/Event.js').Event} event - The stored event (the master for an occurrence id)
+ * @property {string} eventId - Id of the stored event, as kept in the state's selectedEventId
+ * @property {string|null} occurrenceId - The occurrence id that was selected, or null for a stored event's id
+ * @property {import('./events/Event.js').Event|null} occurrence - The selected occurrence as in view data, or null
+ */
 /**
  * @typedef {Object} QueryFilters
  * @property {Date} [start] - Start date for range query