@forcecalendar/interface 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forcecalendar/interface",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Official interface layer for forceCalendar Core - Enterprise calendar components",
   "main": "dist/force-calendar-interface.umd.js",
@@ -20,9 +20,9 @@
     "types/**/*.d.ts"
   ],
   "sideEffects": [
+    "./dist/*.js",
     "./src/index.js",
-    "./src/components/ForceCalendar.js",
-    "./src/components/EventForm.js"
+    "./src/components/*.js"
   ],
   "scripts": {
     "dev": "vite",
@@ -58,7 +58,7 @@
   "devDependencies": {
     "@babel/core": "^7.28.5",
     "@babel/preset-env": "^7.28.5",
-    "@forcecalendar/core": "^2.1.68",
+    "@forcecalendar/core": "^2.5.0",
     "babel-jest": "^30.2.0",
     "eslint": "^8.57.1",
     "jest": "^30.2.0",

package/src/components/ForceCalendar.js

@@ -6,7 +6,7 @@
 
 import { BaseComponent } from '../core/BaseComponent.js';
 import StateManager from '../core/StateManager.js';
-import { StyleUtils } from '../utils/StyleUtils.js';
+import { StyleUtils, THEME_PRESETS } from '../utils/StyleUtils.js';
 import { DateUtils } from '../utils/DateUtils.js';
 import { DOMUtils } from '../utils/DOMUtils.js';
 
@@ -26,7 +26,7 @@ export class ForceCalendar extends BaseComponent {
   };
 
   static get observedAttributes() {
-    return ['view', 'date', 'locale', 'timezone', 'week-starts-on', 'height'];
+    return ['view', 'date', 'locale', 'timezone', 'week-starts-on', 'height', 'theme'];
   }
 
   constructor() {
@@ -35,6 +35,7 @@ export class ForceCalendar extends BaseComponent {
     this.currentView = null;
     this._hasRendered = false; // Track if initial render is complete
     this._busUnsubscribers = [];
+    this._pendingEvents = null; // Snapshot assigned before the state manager exists
   }
 
   /**
@@ -86,6 +87,30 @@ export class ForceCalendar extends BaseComponent {
 
     // Listen for events
     this.setupEventListeners();
+
+    // Frameworks may assign `events` before the element is upgraded (for
+    // example when the component is imported lazily); re-run the setter so
+    // the snapshot reaches the state manager instead of shadowing the accessor.
+    this._upgradeProperty('events');
+    if (this._pendingEvents) {
+      const pending = this._pendingEvents;
+      this._pendingEvents = null;
+      this.stateManager.setEvents(pending.events, pending.options);
+    }
+  }
+
+  /**
+   * Re-apply a property that was set as an own data property before the
+   * custom element was upgraded, so the class accessor sees the value.
+   * @param {string} name
+   * @private
+   */
+  _upgradeProperty(name) {
+    if (Object.prototype.hasOwnProperty.call(this, name)) {
+      const value = this[name];
+      delete this[name];
+      this[name] = value;
+    }
   }
 
   setupEventListeners() {
@@ -150,6 +175,21 @@ export class ForceCalendar extends BaseComponent {
       })
     );
 
+    // Snapshot loads (setEvents / events property) — one event per snapshot
+    this._busUnsubscribers.push(
+      bus.on('events:set', data => {
+        this.emit('calendar-events-set', data);
+      })
+    );
+
+    // Visible window changes (view, date or week start), emitted after the
+    // navigation / view-change events that caused them
+    this._busUnsubscribers.push(
+      bus.on('range:changed', data => {
+        this.emit('calendar-range-change', data);
+      })
+    );
+
     // Date selection events
     this._busUnsubscribers.push(
       bus.on('date:selected', data => {
@@ -276,6 +316,17 @@ export class ForceCalendar extends BaseComponent {
   }
 
   mount() {
+    // Re-entrant: connectedCallback runs again whenever the element is moved
+    // or re-attached (React reconciliation/portals, LWC re-render, StrictMode
+    // double-mount). The StateManager survives unmount(), so only the bindings
+    // released there are restored here; after an explicit destroy() start over.
+    if (!this.stateManager || !this.stateManager.state) {
+      this.initialize();
+    }
+    if (!this._stateUnsubscribe) {
+      this._stateUnsubscribe = this.stateManager.subscribe(this.handleStateChange.bind(this));
+      this.setupEventListeners();
+    }
     this.currentView = this.stateManager.getView();
     super.mount();
   }
@@ -801,7 +852,25 @@ export class ForceCalendar extends BaseComponent {
     return '<div id="calendar-view-container"></div>';
   }
 
+  /**
+   * Apply a named theme preset (e.g. theme="slds") as host-level custom
+   * properties so it cascades into the shadow DOM and stays overridable
+   * by page-level --fc-* variables.
+   */
+  _applyTheme(name) {
+    const preset = THEME_PRESETS[name];
+    for (const token of Object.keys(THEME_PRESETS.slds)) {
+      if (preset && preset[token]) {
+        this.style.setProperty(token, preset[token]);
+      } else {
+        this.style.removeProperty(token);
+      }
+    }
+  }
+
   afterRender() {
+    this._applyTheme(this.getAttribute('theme'));
+
     // Manually instantiate and mount view renderer (bypasses Locker Service)
     const container = this.$('#calendar-view-container');
 
@@ -893,7 +962,19 @@ export class ForceCalendar extends BaseComponent {
     }
 
     // Mark initial render as complete for targeted updates
+    const firstRender = !this._hasRendered;
     this._hasRendered = true;
+
+    // Announce the initial visible window once the first mount is complete so
+    // consumers can load data for it without waiting for a navigation
+    if (firstRender && this.stateManager) {
+      const state = this.stateManager.getState();
+      this.emit('calendar-range-change', {
+        ...this.stateManager.getVisibleRange(),
+        view: state.view,
+        date: state.currentDate
+      });
+    }
   }
 
   handleNavigation(event) {
@@ -973,6 +1054,58 @@ export class ForceCalendar extends BaseComponent {
     return this.stateManager.getEvents();
   }
 
+  /**
+   * Replace the calendar's events with a complete snapshot, applying only the
+   * differences: unchanged events keep their instance, changed ones are
+   * replaced, new ones are added and events missing from the snapshot are
+   * removed unless `removeMissing` is false. The view re-renders at most once
+   * and a single `calendar-events-set` event describes the change set; no
+   * per-event `calendar-event-add`/`-remove` events are dispatched.
+   *
+   * Before the element is connected the snapshot is stored and applied on
+   * initialisation, in which case `null` is returned.
+   *
+   * @param {Iterable<object|import('../core/StateManager.js').CalendarEvent>} events - Complete snapshot of events
+   * @param {import('../core/StateManager.js').EventsSetOptions} [options={}]
+   * @returns {import('../core/StateManager.js').EventsSetResult|null}
+   */
+  setEvents(events, options = {}) {
+    if (!this.stateManager) {
+      this._pendingEvents = { events: events ? Array.from(events) : [], options };
+      return null;
+    }
+    return this.stateManager.setEvents(events, options);
+  }
+
+  /**
+   * Declarative form of {@link ForceCalendar#setEvents}: assign a complete
+   * snapshot and the calendar reconciles it with `removeMissing: true`.
+   * Reading it returns the events currently held by the calendar.
+   *
+   * @returns {import('../core/StateManager.js').CalendarEvent[]}
+   */
+  get events() {
+    if (this.stateManager) return this.stateManager.getEvents();
+    return this._pendingEvents ? this._pendingEvents.events : [];
+  }
+
+  /**
+   * @param {Iterable<object|import('../core/StateManager.js').CalendarEvent>|null} events - Complete snapshot of events
+   */
+  set events(events) {
+    this.setEvents(events);
+  }
+
+  /**
+   * Get the window of dates the current view covers (leading and trailing
+   * other-month days included). `end` is inclusive.
+   *
+   * @returns {import('../core/StateManager.js').VisibleRange|null} The range, or null before the element is initialised
+   */
+  getVisibleRange() {
+    return this.stateManager ? this.stateManager.getVisibleRange() : null;
+  }
+
   setView(view) {
     this.stateManager.setView(view);
   }
@@ -994,11 +1127,22 @@ export class ForceCalendar extends BaseComponent {
   }
 
   unmount() {
-    // Called by disconnectedCallback — clean up all subscriptions
-    this.destroy();
+    // Called by disconnectedCallback. Release everything bound to the rendered
+    // tree (subscriptions, view renderer and its timers, DOM listeners) but keep
+    // the StateManager so the element keeps its view, date and events when it
+    // is re-attached. Full teardown is opt-in via destroy().
+    this._releaseBindings();
   }
 
   destroy() {
+    this._releaseBindings();
+
+    if (this.stateManager) {
+      this.stateManager.destroy();
+    }
+  }
+
+  _releaseBindings() {
     this._busUnsubscribers.forEach(unsub => unsub());
     this._busUnsubscribers = [];
 
@@ -1009,12 +1153,9 @@ export class ForceCalendar extends BaseComponent {
 
     if (this._currentViewInstance && this._currentViewInstance.cleanup) {
       this._currentViewInstance.cleanup();
-      this._currentViewInstance = null;
-    }
-
-    if (this.stateManager) {
-      this.stateManager.destroy();
     }
+    this._currentViewInstance = null;
+    this._hasRendered = false;
     super.cleanup();
   }
 }

package/src/core/BaseComponent.js

@@ -31,6 +31,10 @@ export class BaseComponent extends HTMLElement {
   disconnectedCallback() {
     this.unmount();
     this.cleanup();
+    // Drop the rendered tree so a later re-attach starts from an empty shadow
+    // root instead of appending a second style/content pair next to the old one.
+    if (this._styleEl) this._styleEl.remove();
+    if (this._contentWrapper) this._contentWrapper.remove();
     this._styleEl = null;
     this._contentWrapper = null;
   }

package/src/core/StateManager.js

@@ -8,6 +8,40 @@
 import { Calendar } from '@forcecalendar/core';
 import { EventBus } from './EventBus.js';
 
+/**
+ * @typedef {import('@forcecalendar/core').Event} CalendarEvent
+ */
+
+/**
+ * @typedef {Object} EventsSetOptions
+ * @property {boolean} [removeMissing=true] - Remove stored events that are absent from the snapshot
+ */
+
+/**
+ * @typedef {Object} EventsSetUpdate
+ * @property {CalendarEvent} event - Event now held by the calendar
+ * @property {CalendarEvent} oldEvent - Event instance it replaced
+ */
+
+/**
+ * @typedef {Object} EventsSetResult
+ * @property {CalendarEvent[]} events - All events after the snapshot was applied
+ * @property {CalendarEvent[]} added - Events that were not present before
+ * @property {EventsSetUpdate[]} updated - Events whose data changed
+ * @property {CalendarEvent[]} removed - Events dropped because they were missing from the snapshot
+ * @property {CalendarEvent[]} unchanged - Events left untouched (same instances as before)
+ */
+
+/**
+ * @typedef {Object} VisibleRange
+ * @property {Date} start - First instant shown by the current view
+ * @property {Date} end - Last instant shown by the current view (inclusive)
+ */
+
+/**
+ * @typedef {VisibleRange & { view: string, date: Date }} VisibleRangeChange
+ */
+
 class StateManager {
   constructor(config = {}) {
     // Each StateManager gets its own EventBus to prevent cross-instance
@@ -46,6 +80,9 @@ class StateManager {
 
     // Initial sync of events from Core (in case events were pre-loaded)
     this._syncEventsFromCore({ silent: true });
+
+    // Remember the visible window so range:changed only fires on real changes
+    this._visibleRangeKey = this._rangeKey(this.getVisibleRange());
   }
 
   /**
@@ -183,6 +220,7 @@ class StateManager {
     this.calendar.setView(view);
     this.setState({ view });
     this.eventBus.emit('view:changed', { view });
+    this._syncVisibleRange();
   }
 
   getView() {
@@ -193,6 +231,7 @@ class StateManager {
     this.calendar.goToDate(date);
     this.setState({ currentDate: this.calendar.getCurrentDate() });
     this.eventBus.emit('date:changed', { date: this.state.currentDate });
+    this._syncVisibleRange();
   }
 
   getCurrentDate() {
@@ -204,24 +243,28 @@ class StateManager {
     this.calendar.next();
     this.setState({ currentDate: this.calendar.getCurrentDate() });
     this.eventBus.emit('navigation:next', { date: this.state.currentDate });
+    this._syncVisibleRange();
   }
 
   previous() {
     this.calendar.previous();
     this.setState({ currentDate: this.calendar.getCurrentDate() });
     this.eventBus.emit('navigation:previous', { date: this.state.currentDate });
+    this._syncVisibleRange();
   }
 
   today() {
     this.calendar.today();
     this.setState({ currentDate: this.calendar.getCurrentDate() });
     this.eventBus.emit('navigation:today', { date: this.state.currentDate });
+    this._syncVisibleRange();
   }
 
   goToDate(date) {
     this.calendar.goToDate(date);
     this.setState({ currentDate: this.calendar.getCurrentDate() });
     this.eventBus.emit('navigation:goto', { date: this.state.currentDate });
+    this._syncVisibleRange();
   }
 
   // Event management
@@ -285,6 +328,133 @@ class StateManager {
     return this.calendar.getEvents() || [];
   }
 
+  /**
+   * Replace the calendar's events with a complete snapshot, applying only the
+   * differences.
+   *
+   * Unchanged events keep their existing instance, changed ones are replaced,
+   * new ones are added and events missing from the snapshot are removed
+   * (unless `removeMissing` is false). The state is updated at most once and a
+   * single `events:set` bus event carries the change set. The per-event
+   * `event:add`/`event:added`/`event:remove`/`event:deleted` events are NOT
+   * emitted, so listeners that persist user edits are not triggered by a
+   * snapshot load.
+   *
+   * Uses `Calendar#reconcileEvents` when the installed core provides it
+   * (2.4.0+) and falls back to an id-based diff on older cores.
+   *
+   * @param {Iterable<object|CalendarEvent>} events - Complete snapshot of events
+   * @param {EventsSetOptions} [options={}]
+   * @returns {EventsSetResult} The applied change set
+   * @throws {Error} If an entry fails validation or two entries share an id (an `event:error` bus event is emitted first)
+   */
+  setEvents(events, options = {}) {
+    const { removeMissing = true } = options;
+    const snapshot = events ? Array.from(events) : [];
+
+    let result;
+    try {
+      result =
+        typeof this.calendar.reconcileEvents === 'function'
+          ? this.calendar.setEvents(snapshot, { reconcile: true, removeMissing })
+          : this._reconcileFallback(snapshot, removeMissing);
+    } catch (error) {
+      // Nothing has been applied (core rolls the batch back), so surface the
+      // problem to the caller instead of leaving the snapshot half-loaded
+      this.eventBus.emit('event:error', { action: 'set', events: snapshot, error });
+      throw error;
+    }
+
+    const { added, updated, removed, unchanged } = result;
+    /** @type {EventsSetResult} */
+    const payload = { events: this.getEvents(), added, updated, removed, unchanged };
+
+    if (added.length > 0 || updated.length > 0 || removed.length > 0) {
+      this.setState({ events: [...payload.events] });
+    }
+    this.eventBus.emit('events:set', payload);
+    return payload;
+  }
+
+  /**
+   * Id-based diff for cores that predate `Calendar#reconcileEvents`.
+   * Works on the core calendar directly so no per-event bus events fire.
+   * Equivalence is approximated by comparing the fields present in the
+   * snapshot entry, so an entry that only omits fields is treated as unchanged.
+   *
+   * @param {Array<object|CalendarEvent>} snapshot
+   * @param {boolean} removeMissing
+   * @returns {{ added: CalendarEvent[], updated: EventsSetUpdate[], removed: CalendarEvent[], unchanged: CalendarEvent[] }}
+   * @private
+   */
+  _reconcileFallback(snapshot, removeMissing) {
+    const incoming = new Map();
+    snapshot.forEach(entry => {
+      const id = entry && entry.id;
+      if (id === undefined || id === null || id === '') {
+        throw new Error('Every event in a snapshot must have an id');
+      }
+      if (incoming.has(id)) {
+        throw new Error(`Duplicate event id in snapshot: ${id}`);
+      }
+      incoming.set(id, entry);
+    });
+
+    const result = { added: [], updated: [], removed: [], unchanged: [] };
+    const existingById = new Map(this.getEvents().map(event => [event.id, event]));
+
+    if (removeMissing) {
+      existingById.forEach((existing, id) => {
+        if (!incoming.has(id) && this.calendar.removeEvent(id)) {
+          result.removed.push(existing);
+        }
+      });
+    }
+
+    incoming.forEach((entry, id) => {
+      const existing = existingById.get(id);
+      const data = typeof entry.toObject === 'function' ? entry.toObject() : entry;
+      if (!existing) {
+        const event = this.calendar.addEvent(entry);
+        if (!event) throw new Error(`Failed to add event: ${id}`);
+        result.added.push(event);
+      } else if (existing === entry || this._isEquivalentFallback(existing, data)) {
+        result.unchanged.push(existing);
+      } else {
+        const event = this.calendar.updateEvent(id, data);
+        if (!event) throw new Error(`Failed to update event: ${id}`);
+        result.updated.push({ event, oldEvent: existing });
+      }
+    });
+
+    return result;
+  }
+
+  /**
+   * Field-wise comparison of a stored event against snapshot data.
+   * @param {CalendarEvent} existing
+   * @param {object} data
+   * @returns {boolean}
+   * @private
+   */
+  _isEquivalentFallback(existing, data) {
+    const toTime = value => {
+      if (value instanceof Date) return value.getTime();
+      if (value === undefined || value === null) return NaN;
+      return new Date(value).getTime();
+    };
+    return Object.keys(data).every(key => {
+      const stored = existing[key];
+      const incoming = data[key];
+      if (key === 'start' || key === 'end') return toTime(stored) === toTime(incoming);
+      if (stored === incoming) return true;
+      if (stored === undefined || stored === null || incoming === undefined || incoming === null) {
+        return false;
+      }
+      return JSON.stringify(stored) === JSON.stringify(incoming);
+    });
+  }
+
   /**
    * Force sync state.events from Core calendar
    * Use this if you've modified events directly on the Core calendar
@@ -351,6 +521,70 @@ class StateManager {
     return enriched;
   }
 
+  // Visible range
+
+  /**
+   * Get the window of dates the current view covers, including leading and
+   * trailing days from adjacent months in the month view.
+   *
+   * `end` is the last millisecond of the window (inclusive), so the pair can
+   * be passed straight to {@link StateManager#getEventsInRange}.
+   *
+   * @returns {VisibleRange}
+   */
+  getVisibleRange() {
+    const view = this.calendar.getView();
+    const date = this.calendar.getCurrentDate();
+
+    if (view !== 'day') {
+      const viewData = this.calendar.getViewData() || {};
+      if (viewData.startDate instanceof Date && viewData.endDate instanceof Date) {
+        const start = new Date(viewData.startDate);
+        let end = new Date(viewData.endDate);
+        // The list view reports an exclusive end; normalise it to inclusive
+        if (viewData.type === 'list') {
+          end = new Date(end.getTime() - 1);
+        }
+        return { start, end };
+      }
+    }
+
+    // Day view (or a view without an explicit window): midnight to midnight
+    const start = new Date(date);
+    start.setHours(0, 0, 0, 0);
+    const end = new Date(start);
+    end.setDate(end.getDate() + 1);
+    end.setMilliseconds(-1);
+    return { start, end };
+  }
+
+  /**
+   * @param {VisibleRange} range
+   * @returns {string}
+   * @private
+   */
+  _rangeKey(range) {
+    return `${range.start.getTime()}:${range.end.getTime()}`;
+  }
+
+  /**
+   * Single choke point for `range:changed`: recompute the visible window and
+   * emit only when it differs from the last one that was announced.
+   * Called after view, date and week-start changes, once their own bus events
+   * have been emitted, so listeners see navigation before the range update.
+   * @private
+   */
+  _syncVisibleRange() {
+    if (!this.calendar) return;
+    const range = this.getVisibleRange();
+    const key = this._rangeKey(range);
+    if (key === this._visibleRangeKey) return;
+    this._visibleRangeKey = key;
+    /** @type {VisibleRangeChange} */
+    const payload = { ...range, view: this.state.view, date: this.state.currentDate };
+    this.eventBus.emit('range:changed', payload);
+  }
+
   // Selection management
   selectEvent(event) {
     this.setState({ selectedEvent: event });
@@ -420,6 +654,7 @@ class StateManager {
     // Update calendar configuration if needed
     if (config.weekStartsOn !== undefined) {
       this.calendar.setWeekStartsOn(config.weekStartsOn);
+      this._syncVisibleRange();
     }
     if (config.locale !== undefined) {
       this.calendar.setLocale(config.locale);

package/src/index.js

@@ -23,3 +23,4 @@ export { DayViewRenderer } from './renderers/DayViewRenderer.js';
 
 // Components
 export { ForceCalendar } from './components/ForceCalendar.js';
+export { EventForm } from './components/EventForm.js';

package/src/utils/StyleUtils.js

@@ -2,6 +2,34 @@
  * StyleUtils - Styling utilities and theme management
  */
 
+/**
+ * Named theme presets applied via the <forcecal-main theme="..."> attribute.
+ * Each maps design tokens to a platform's visual language.
+ */
+export const THEME_PRESETS = {
+  // Salesforce Lightning Design System: looks native on the platform
+  slds: {
+    '--fc-primary-color': '#0176d3',
+    '--fc-primary-hover': '#014486',
+    '--fc-primary-light': '#eef4ff',
+    '--fc-accent-color': '#0b5cab',
+    '--fc-text-color': '#181818',
+    '--fc-text-secondary': '#706e6b',
+    '--fc-text-light': '#939393',
+    '--fc-border-color': '#e5e5e5',
+    '--fc-border-color-hover': '#c9c9c9',
+    '--fc-background': '#ffffff',
+    '--fc-background-alt': '#f3f3f3',
+    '--fc-background-hover': '#f3f3f3',
+    '--fc-background-active': '#d8e6fe',
+    '--fc-danger-color': '#ea001e',
+    '--fc-success-color': '#2e844a',
+    '--fc-border-radius': '0.25rem',
+    '--fc-border-radius-sm': '0.125rem',
+    '--fc-font-family': "'Salesforce Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
+  }
+};
+
 export class StyleUtils {
   /**
    * Default theme colors