@forcecalendar/interface 1.5.0 → 1.6.0

package/types/core/StateManager.d.ts

@@ -4,13 +4,95 @@
  * Wraps the @forcecalendar/core Calendar instance
  * Provides reactive state updates and component synchronization
  */
+import { Calendar } from '@forcecalendar/core';
 import { EventBus } from './EventBus.js';
+export type CalendarEvent = import('@forcecalendar/core').Event;
+export type EventsSetOptions = {
+    /**
+     * - Remove stored events that are absent from the snapshot
+     */
+    removeMissing?: boolean;
+};
+export type EventsSetUpdate = {
+    /**
+     * - Event now held by the calendar
+     */
+    event: CalendarEvent;
+    /**
+     * - Event instance it replaced
+     */
+    oldEvent: CalendarEvent;
+};
+export type EventsSetResult = {
+    /**
+     * - All events after the snapshot was applied
+     */
+    events: CalendarEvent[];
+    /**
+     * - Events that were not present before
+     */
+    added: CalendarEvent[];
+    /**
+     * - Events whose data changed
+     */
+    updated: EventsSetUpdate[];
+    /**
+     * - Events dropped because they were missing from the snapshot
+     */
+    removed: CalendarEvent[];
+    /**
+     * - Events left untouched (same instances as before)
+     */
+    unchanged: CalendarEvent[];
+};
+export type VisibleRange = {
+    /**
+     * - First instant shown by the current view
+     */
+    start: Date;
+    /**
+     * - Last instant shown by the current view (inclusive)
+     */
+    end: Date;
+};
+export type VisibleRangeChange = VisibleRange & {
+    view: string;
+    date: Date;
+};
+/**
+ * @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
+ */
 declare class StateManager {
     eventBus: EventBus;
-    calendar: any;
+    calendar: Calendar;
     state: {
-        view: any;
-        currentDate: any;
+        view: import("@forcecalendar/core/types").ViewType;
+        currentDate: Date;
         events: never[];
         selectedEvent: null;
         selectedDate: null;
@@ -19,6 +101,7 @@ declare class StateManager {
         config: {};
     };
     subscribers: Set<any>;
+    _visibleRangeKey: string;
     _subscriberIds: Map<any, any> | null | undefined;
     constructor(config?: {});
     /**
@@ -34,7 +117,7 @@ declare class StateManager {
     _syncEventsFromCore(options?: {
         silent: boolean;
         force: boolean;
-    }): any;
+    }): import("@forcecalendar/core").Event[];
     /**
      * Check if two event arrays have the same events by id.
      * Only used for add/delete guards — updateEvent must pass force:true
@@ -42,8 +125,8 @@ declare class StateManager {
      */
     _eventsMatch(arr1: any, arr2: any): any;
     getState(): {
-        view: any;
-        currentDate: any;
+        view: import("@forcecalendar/core/types").ViewType;
+        currentDate: Date;
         selectedEvent: null;
         selectedDate: null;
         loading: boolean;
@@ -52,8 +135,8 @@ declare class StateManager {
         events: never[];
     };
     setState(updates: any, options?: {}): {
-        view: any;
-        currentDate: any;
+        view: import("@forcecalendar/core/types").ViewType;
+        currentDate: Date;
         events: never[];
         selectedEvent: null;
         selectedDate: null;
@@ -75,26 +158,91 @@ declare class StateManager {
     notifySubscribers(oldState: any, newState: any): void;
     emitStateChange(oldState: any, newState: any): void;
     setView(view: any): void;
-    getView(): any;
+    getView(): import("@forcecalendar/core/types").ViewType;
     setDate(date: any): void;
-    getCurrentDate(): any;
+    getCurrentDate(): Date;
     next(): void;
     previous(): void;
     today(): void;
     goToDate(date: any): void;
-    addEvent(event: any): any;
-    updateEvent(eventId: any, updates: any): any;
+    addEvent(event: any): import("@forcecalendar/core").Event | null;
+    updateEvent(eventId: any, updates: any): import("@forcecalendar/core").Event | null;
     deleteEvent(eventId: any): boolean;
-    getEvents(): any;
+    getEvents(): import("@forcecalendar/core").Event[];
+    /**
+     * 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: Iterable<object | CalendarEvent>, options?: EventsSetOptions): EventsSetResult;
+    /**
+     * 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
+     */
+    private _reconcileFallback;
+    /**
+     * Field-wise comparison of a stored event against snapshot data.
+     * @param {CalendarEvent} existing
+     * @param {object} data
+     * @returns {boolean}
+     * @private
+     */
+    private _isEquivalentFallback;
     /**
      * Force sync state.events from Core calendar
      * Use this if you've modified events directly on the Core calendar
      */
-    syncEvents(): any;
-    getEventsForDate(date: any): any;
-    getEventsInRange(start: any, end: any): any;
+    syncEvents(): import("@forcecalendar/core").Event[];
+    getEventsForDate(date: any): import("@forcecalendar/core").Event[];
+    getEventsInRange(start: any, end: any): import("@forcecalendar/core").Event[];
     getViewData(): any;
     enrichViewData(viewData: any): any;
+    /**
+     * 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(): VisibleRange;
+    /**
+     * @param {VisibleRange} range
+     * @returns {string}
+     * @private
+     */
+    private _rangeKey;
+    /**
+     * 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
+     */
+    private _syncVisibleRange;
     selectEvent(event: any): void;
     selectEventById(eventId: any): void;
     deselectEvent(): void;

package/types/index.d.ts

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

package/types/utils/DateUtils.d.ts

@@ -28,7 +28,7 @@ export declare class DateUtils extends CoreDateUtils {
     /**
      * Check if date is today
      */
-    static isToday(date: any): any;
+    static isToday(date: any): boolean;
     /**
      * Check if date is in the past
      */