@forcecalendar/interface 1.4.0 → 1.6.0

package/types/components/ForceCalendar.d.ts

@@ -14,6 +14,10 @@ export declare class ForceCalendar extends BaseComponent {
     currentView: any;
     _hasRendered: boolean;
     _busUnsubscribers: any[];
+    _pendingEvents: {
+        events: (object | import("@forcecalendar/core").Event)[];
+        options: import("../core/StateManager.js").EventsSetOptions;
+    } | null;
     _stateUnsubscribe: (() => void) | null | undefined;
     _currentViewInstance: any;
     _viewUnsubscribe: any;
@@ -32,6 +36,13 @@ export declare class ForceCalendar extends BaseComponent {
      */
     propChanged(name: any, oldValue: any, newValue: any): void;
     initialize(): void;
+    /**
+     * 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
+     */
+    private _upgradeProperty;
     setupEventListeners(): void;
     handleStateChange(newState: any, oldState: any): void;
     /**
@@ -59,15 +70,56 @@ export declare class ForceCalendar extends BaseComponent {
     getStyles(): string;
     template(): string;
     renderView(): string;
+    /**
+     * 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: any): void;
     afterRender(): void;
     handleNavigation(event: any): void;
     handleViewChange(event: any): void;
     getTitle(date: any, view: any): string;
     getIcon(name: any): any;
-    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 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: Iterable<object | import('../core/StateManager.js').CalendarEvent>, options?: import('../core/StateManager.js').EventsSetOptions): import('../core/StateManager.js').EventsSetResult | null;
+    /**
+     * 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(): import('../core/StateManager.js').CalendarEvent[];
+    /**
+     * @param {Iterable<object|import('../core/StateManager.js').CalendarEvent>|null} events - Complete snapshot of events
+     */
+    set events(events: Iterable<object | import('../core/StateManager.js').CalendarEvent> | null);
+    /**
+     * 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(): import('../core/StateManager.js').VisibleRange | null;
     setView(view: any): void;
     setDate(date: any): void;
     next(): void;
@@ -75,4 +127,5 @@ export declare class ForceCalendar extends BaseComponent {
     today(): void;
     unmount(): void;
     destroy(): void;
+    _releaseBindings(): void;
 }

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
      */

package/types/utils/StyleUtils.d.ts

@@ -1,6 +1,32 @@
 /**
  * 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 declare const THEME_PRESETS: {
+    slds: {
+        '--fc-primary-color': string;
+        '--fc-primary-hover': string;
+        '--fc-primary-light': string;
+        '--fc-accent-color': string;
+        '--fc-text-color': string;
+        '--fc-text-secondary': string;
+        '--fc-text-light': string;
+        '--fc-border-color': string;
+        '--fc-border-color-hover': string;
+        '--fc-background': string;
+        '--fc-background-alt': string;
+        '--fc-background-hover': string;
+        '--fc-background-active': string;
+        '--fc-danger-color': string;
+        '--fc-success-color': string;
+        '--fc-border-radius': string;
+        '--fc-border-radius-sm': string;
+        '--fc-font-family': string;
+    };
+};
 export declare class StyleUtils {
     /**
      * Default theme colors