@forcecalendar/interface 1.1.0 → 1.2.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@forcecalendar/interface",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Official interface layer for forceCalendar Core - Enterprise calendar components",
   "main": "dist/force-calendar-interface.umd.js",
   "module": "dist/force-calendar-interface.esm.js",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./dist/force-calendar-interface.esm.js",
       "require": "./dist/force-calendar-interface.umd.js"
     }
@@ -15,7 +16,8 @@
   "jsdelivr": "dist/force-calendar-interface.umd.js",
   "files": [
     "dist",
-    "src"
+    "src",
+    "types/**/*.d.ts"
   ],
   "sideEffects": [
     "./src/index.js",
@@ -26,7 +28,9 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
-    "test": "jest --testTimeout=10000"
+    "test": "jest --testTimeout=10000",
+    "build:types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm run build && npm run build:types"
   },
   "repository": {
     "type": "git",
@@ -60,6 +64,8 @@
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "prettier": "^3.8.1",
+    "typescript": "^7.0.2",
     "vite": "^8.1.4"
-  }
+  },
+  "types": "./types/index.d.ts"
 }

package/types/components/EventForm.d.ts

@@ -0,0 +1,42 @@
+import { BaseComponent } from '../core/BaseComponent.js';
+export declare class EventForm extends BaseComponent {
+    _isVisible: boolean;
+    _cleanupFocusTrap: (() => any) | null;
+    config: {
+        title: string;
+        defaultDuration: number;
+        colors: {
+            color: string;
+            label: string;
+        }[];
+    };
+    _formData: {
+        title: string;
+        start: Date;
+        end: Date;
+        allDay: boolean;
+        color: string;
+    };
+    modalContent: any;
+    titleInput: any;
+    startInput: any;
+    endInput: any;
+    colorContainer: any;
+    titleGroup: any;
+    endGroup: any;
+    _handleKeyDown: ((e: any) => void) | null | undefined;
+    _keydownListenerAdded: boolean | undefined;
+    constructor();
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: any, oldValue: any, newValue: any): void;
+    getStyles(): string;
+    template(): string;
+    afterRender(): void;
+    updateColorSelection(): void;
+    open(initialDate?: Date): void;
+    close(): void;
+    validate(): boolean;
+    save(): void;
+    formatDateForInput(date: any): string;
+    unmount(): void;
+}

package/types/components/ForceCalendar.d.ts

@@ -0,0 +1,78 @@
+/**
+ * ForceCalendar - Main calendar component
+ *
+ * The primary interface component that integrates all views and features
+ */
+import { BaseComponent } from '../core/BaseComponent.js';
+import StateManager from '../core/StateManager.js';
+import { MonthViewRenderer } from '../renderers/MonthViewRenderer.js';
+import { WeekViewRenderer } from '../renderers/WeekViewRenderer.js';
+import { DayViewRenderer } from '../renderers/DayViewRenderer.js';
+import './EventForm.js';
+export declare class ForceCalendar extends BaseComponent {
+    stateManager: StateManager | null;
+    currentView: any;
+    _hasRendered: boolean;
+    _busUnsubscribers: any[];
+    _stateUnsubscribe: (() => void) | null | undefined;
+    _currentViewInstance: any;
+    _viewUnsubscribe: any;
+    static RENDERERS: {
+        month: typeof MonthViewRenderer;
+        week: typeof WeekViewRenderer;
+        day: typeof DayViewRenderer;
+    };
+    static get observedAttributes(): string[];
+    constructor();
+    /**
+     * Route observed-attribute changes into the StateManager.
+     * Without this, attribute updates after mount (view, locale, timezone,
+     * week-starts-on, date) only re-rendered from stale state and had no
+     * visible effect. 'height' is presentational and picked up by render().
+     */
+    propChanged(name: any, oldValue: any, newValue: any): void;
+    initialize(): void;
+    setupEventListeners(): void;
+    handleStateChange(newState: any, oldState: any): void;
+    /**
+     * Update only the title text (no DOM recreation)
+     */
+    _updateTitle(): void;
+    /**
+     * Update view button active states (no DOM recreation)
+     */
+    _updateViewButtons(): void;
+    /**
+     * Switch to a different view type
+     */
+    _switchView(): void;
+    /**
+     * Re-render only the view content (not header)
+     */
+    _updateViewContent(): void;
+    /**
+     * Toggle loading overlay without rebuilding the component tree.
+     */
+    _updateLoadingState(isLoading: any): void;
+    mount(): void;
+    loadView(viewType: any): void;
+    getStyles(): string;
+    template(): string;
+    renderView(): string;
+    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;
+    deleteEvent(eventId: any): boolean;
+    getEvents(): any;
+    setView(view: any): void;
+    setDate(date: any): void;
+    next(): void;
+    previous(): void;
+    today(): void;
+    unmount(): void;
+    destroy(): void;
+}

package/types/core/BaseComponent.d.ts

@@ -0,0 +1,68 @@
+/**
+ * BaseComponent - Foundation for all Force Calendar Web Components
+ *
+ * Provides common functionality:
+ * - Shadow DOM setup
+ * - Event handling
+ * - State management integration
+ * - Lifecycle management
+ * - Style management
+ */
+export declare class BaseComponent extends HTMLElement {
+    _listeners: any[];
+    _state: any;
+    _props: Map<any, any>;
+    _initialized: boolean;
+    _styleEl: HTMLStyleElement | null | undefined;
+    _contentWrapper: HTMLDivElement | null | undefined;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    initialize(): void;
+    mount(): void;
+    unmount(): void;
+    cleanup(): void;
+    setState(newState: any): void;
+    getState(): any;
+    stateChanged(_oldState: any, _newState: any): void;
+    setProp(key: any, value: any): void;
+    getProp(key: any): any;
+    propChanged(_key: any, _oldValue: any, _newValue: any): void;
+    addListener(element: any, event: any, handler: any): void;
+    emit(eventName: any, detail?: {}): void;
+    getStyles(): string;
+    getBaseStyles(): string;
+    render(): void;
+    /**
+     * Save scroll positions of all scrollable containers within shadow DOM
+     * @returns {Map<string, {top: number, left: number}>}
+     */
+    _saveScrollPositions(): Map<string, {
+        top: number;
+        left: number;
+    }>;
+    /**
+     * Restore previously saved scroll positions
+     * @param {Map<string, {top: number, left: number}>} positions
+     */
+    _restoreScrollPositions(positions: Map<string, {
+        top: number;
+        left: number;
+    }>): void;
+    /**
+     * Get a CSS selector for the currently focused element within shadow DOM
+     * @returns {string|null}
+     */
+    _getActiveElementSelector(): string | null;
+    /**
+     * Restore focus to a previously focused element
+     * @param {string|null} selector
+     */
+    _restoreFocus(selector: string | null): void;
+    template(): string;
+    afterRender(): void;
+    $(selector: any): any;
+    $$(selector: any): NodeListOf<any>;
+    static get observedAttributes(): never[];
+    attributeChangedCallback(name: any, oldValue: any, newValue: any): void;
+}

package/types/core/EventBus.d.ts

@@ -0,0 +1,71 @@
+/**
+ * EventBus - Central event communication system
+ *
+ * Enables decoupled communication between components
+ * Supports event namespacing and wildcard subscriptions
+ */
+declare class EventBus {
+    events: Map<any, any>;
+    wildcardHandlers: Set<any>;
+    constructor();
+    /**
+     * Subscribe to an event
+     * @param {string} eventName - Event name or pattern (supports wildcards)
+     * @param {Function} handler - Event handler function
+     * @param {Object} options - Subscription options
+     * @returns {Function} Unsubscribe function
+     */
+    on(eventName: string, handler: Function, options?: Object): Function;
+    /**
+     * Subscribe to an event that fires only once
+     */
+    once(eventName: any, handler: any, options?: {}): Function;
+    /**
+     * Unsubscribe from an event
+     */
+    off(eventName: any, handler: any): void;
+    /**
+     * Remove all wildcard handlers matching a pattern
+     * @param {string} pattern - Pattern to match (e.g., 'event:*')
+     */
+    offWildcard(pattern: string): void;
+    /**
+     * Remove all handlers (regular and wildcard) for a specific handler function
+     * Useful for cleanup when a component is destroyed
+     * @param {Function} handler - Handler function to remove
+     */
+    offAll(handler: Function): void;
+    /**
+     * Emit an event synchronously
+     * @param {string} eventName - Event name
+     * @param {*} data - Event data
+     */
+    emit(eventName: string, data: any): void;
+    /**
+     * Check if event name matches a pattern
+     * Only `*` acts as a wildcard; all other characters match literally
+     */
+    matchesPattern(eventName: any, pattern: any): boolean;
+    /**
+     * Clear all event subscriptions
+     */
+    clear(): void;
+    /**
+     * Get all registered event names
+     */
+    getEventNames(): any[];
+    /**
+     * Get handler count for an event
+     */
+    getHandlerCount(eventName: any): any;
+    /**
+     * Get wildcard handler count
+     */
+    getWildcardHandlerCount(): number;
+    /**
+     * Get total handler count (for debugging/monitoring)
+     */
+    getTotalHandlerCount(): number;
+}
+declare const eventBus: EventBus;
+export { EventBus, eventBus as default };

package/types/core/StateManager.d.ts

@@ -0,0 +1,112 @@
+/**
+ * StateManager - Centralized state management for Force Calendar
+ *
+ * Wraps the @forcecalendar/core Calendar instance
+ * Provides reactive state updates and component synchronization
+ */
+import { EventBus } from './EventBus.js';
+declare class StateManager {
+    eventBus: EventBus;
+    calendar: any;
+    state: {
+        view: any;
+        currentDate: any;
+        events: never[];
+        selectedEvent: null;
+        selectedDate: null;
+        loading: boolean;
+        error: null;
+        config: {};
+    };
+    subscribers: Set<any>;
+    _subscriberIds: Map<any, any> | null | undefined;
+    constructor(config?: {});
+    /**
+     * Sync state.events from Core calendar (single source of truth)
+     * This ensures state.events always matches Core's event store.
+     *
+     * @param {object} options
+     * @param {boolean} options.silent  - suppress subscriber notifications
+     * @param {boolean} options.force   - always update even when IDs match
+     *                                    (required after updateEvent where IDs
+     *                                    are unchanged but content has changed)
+     */
+    _syncEventsFromCore(options?: {
+        silent: boolean;
+        force: boolean;
+    }): any;
+    /**
+     * Check if two event arrays have the same events by id.
+     * Only used for add/delete guards — updateEvent must pass force:true
+     * to bypass this check because IDs are unchanged after an update.
+     */
+    _eventsMatch(arr1: any, arr2: any): any;
+    getState(): {
+        view: any;
+        currentDate: any;
+        selectedEvent: null;
+        selectedDate: null;
+        loading: boolean;
+        error: null;
+        config: {};
+        events: never[];
+    };
+    setState(updates: any, options?: {}): {
+        view: any;
+        currentDate: any;
+        events: never[];
+        selectedEvent: null;
+        selectedDate: null;
+        loading: boolean;
+        error: null;
+        config: {};
+    };
+    subscribe(callback: any, subscriberId?: null): () => void;
+    unsubscribe(callback: any, subscriberId?: null): void;
+    /**
+     * Unsubscribe by subscriber ID
+     * @param {string} subscriberId - ID used when subscribing
+     */
+    unsubscribeById(subscriberId: string): boolean;
+    /**
+     * Get subscriber count (for debugging/monitoring)
+     */
+    getSubscriberCount(): number;
+    notifySubscribers(oldState: any, newState: any): void;
+    emitStateChange(oldState: any, newState: any): void;
+    setView(view: any): void;
+    getView(): any;
+    setDate(date: any): void;
+    getCurrentDate(): any;
+    next(): void;
+    previous(): void;
+    today(): void;
+    goToDate(date: any): void;
+    addEvent(event: any): any;
+    updateEvent(eventId: any, updates: any): any;
+    deleteEvent(eventId: any): boolean;
+    getEvents(): any;
+    /**
+     * 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;
+    getViewData(): any;
+    enrichViewData(viewData: any): any;
+    selectEvent(event: any): void;
+    selectEventById(eventId: any): void;
+    deselectEvent(): void;
+    selectDate(date: any): void;
+    deselectDate(): void;
+    isToday(date: any): boolean;
+    isSelectedDate(date: any): null;
+    isWeekend(date: any): boolean;
+    setLoading(loading: any): void;
+    setError(error: any): void;
+    clearError(): void;
+    updateConfig(config: any): void;
+    destroy(): void;
+}
+export default StateManager;

package/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Force Calendar Interface
+ * Main entry point for the component library
+ *
+ * A solid foundation for calendar interfaces built on @forcecalendar/core
+ */
+export { BaseComponent } from './core/BaseComponent.js';
+export { default as StateManager } from './core/StateManager.js';
+export { default as eventBus, EventBus } from './core/EventBus.js';
+export { DateUtils } from './utils/DateUtils.js';
+export { DOMUtils } from './utils/DOMUtils.js';
+export { StyleUtils } from './utils/StyleUtils.js';
+export { BaseViewRenderer } from './renderers/BaseViewRenderer.js';
+export { MonthViewRenderer } from './renderers/MonthViewRenderer.js';
+export { WeekViewRenderer } from './renderers/WeekViewRenderer.js';
+export { DayViewRenderer } from './renderers/DayViewRenderer.js';
+export { ForceCalendar } from './components/ForceCalendar.js';

package/types/renderers/BaseViewRenderer.d.ts

@@ -0,0 +1,122 @@
+/**
+ * BaseViewRenderer - Foundation for all view renderers
+ *
+ * Pure JavaScript class (no Web Components) for Salesforce Locker Service compatibility.
+ * Provides common functionality for rendering calendar views.
+ */
+export declare class BaseViewRenderer {
+    container: HTMLElement;
+    stateManager: StateManager;
+    _listeners: any[];
+    _scrolled: boolean;
+    _nowIndicatorTimer: number | null;
+    /**
+     * @param {HTMLElement} container - The DOM element to render into
+     * @param {StateManager} stateManager - The state manager instance
+     */
+    constructor(container: HTMLElement, stateManager: StateManager);
+    /**
+     * Render the view into the container
+     * Must be implemented by subclasses
+     */
+    render(): void;
+    /**
+     * Clean up event listeners
+     */
+    cleanup(): void;
+    /**
+     * Add an event listener with automatic cleanup tracking
+     * @param {HTMLElement} element
+     * @param {string} event
+     * @param {Function} handler
+     */
+    addListener(element: HTMLElement, event: string, handler: Function): void;
+    /**
+     * Escape HTML to prevent XSS
+     * @param {string} str
+     * @returns {string}
+     */
+    escapeHTML(str: string): string;
+    /**
+     * Check if a date is today
+     * @param {Date} date
+     * @returns {boolean}
+     */
+    isToday(date: Date): boolean;
+    /**
+     * Check if two dates are the same day
+     * @param {Date} date1
+     * @param {Date} date2
+     * @returns {boolean}
+     */
+    isSameDay(date1: Date, date2: Date): boolean;
+    /**
+     * Format hour for display (e.g., "9 AM", "2 PM")
+     * @param {number} hour - Hour in 24-hour format (0-23)
+     * @returns {string}
+     */
+    formatHour(hour: number): string;
+    /**
+     * Format time for display (e.g., "9 AM", "2:30 PM")
+     * @param {Date} date
+     * @returns {string}
+     */
+    formatTime(date: Date): string;
+    /**
+     * Get contrasting text color for a background color.
+     * Delegates to StyleUtils.getContrastColor() as the single implementation.
+     * @param {string} bgColor - Hex color string
+     * @returns {string} '#000000' or '#FFFFFF'
+     */
+    getContrastingTextColor(bgColor: string): string;
+    /**
+     * Render the "now" indicator line for time-based views
+     * @returns {string} HTML string
+     */
+    renderNowIndicator(): string;
+    /**
+     * Start a timer that updates the now indicator position every 60 seconds.
+     * Call this after render() in day/week views that show a now indicator.
+     */
+    startNowIndicatorTimer(): void;
+    /**
+     * Compute overlap layout columns for a list of timed events.
+     * Returns a Map of event.id -> { column, totalColumns }.
+     * Uses a greedy left-to-right column packing algorithm.
+     * @param {Array} events - Array of event objects with start/end dates
+     * @returns {Map<string, {column: number, totalColumns: number}>}
+     */
+    computeOverlapLayout(events: any[]): Map<string, {
+        column: number;
+        totalColumns: number;
+    }>;
+    /**
+     * Render a timed event block
+     * @param {Object} event - Event object
+     * @param {Object} options - Rendering options
+     * @param {Object} options.compact - Use compact layout
+     * @param {Object} options.overlapLayout - Map from computeOverlapLayout()
+     * @returns {string} HTML string
+     */
+    renderTimedEvent(event: Object, options?: {
+        compact: Object;
+        overlapLayout: Object;
+    }): string;
+    /**
+     * Get a safe, sanitized event color value.
+     * @param {Object} event
+     * @returns {string}
+     */
+    getEventColor(event: Object): string;
+    /**
+     * Attach common event handlers for day/event clicks
+     */
+    attachCommonEventHandlers(): void;
+    _selectEventFromElement(eventEl: any): void;
+    /**
+     * Make rendered events keyboard-reachable and screen-reader labeled.
+     * Runs after every render, across all views.
+     */
+    _enhanceEventAccessibility(): void;
+}
+export default BaseViewRenderer;

package/types/renderers/DayViewRenderer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DayViewRenderer - Renders single day calendar view
+ *
+ * Pure JavaScript renderer for day view, compatible with Salesforce Locker Service.
+ */
+import { BaseViewRenderer } from './BaseViewRenderer.js';
+export declare class DayViewRenderer extends BaseViewRenderer {
+    hourHeight: number;
+    totalHeight: number;
+    constructor(container: any, stateManager: any);
+    render(): void;
+    _renderDayView(viewData: any, _config: any): string;
+    _extractDayData(viewData: any, currentDate: any): {
+        dayDate: Date;
+        dayName: any;
+        isToday: any;
+        allDayEvents: any;
+        timedEvents: any;
+    } | null;
+    _renderHeader(dayDate: any, dayName: any, isToday: any): string;
+    _renderAllDayRow(allDayEvents: any, dayDate: any): string;
+    _renderTimeGrid(timedEvents: any, isToday: any, dayDate: any, hours: any): string;
+    _renderTimeGutter(hours: any): string;
+    _renderDayColumn(timedEvents: any, isToday: any, dayDate: any, hours: any): string;
+    _attachEventHandlers(): void;
+    _scrollToCurrentTime(): void;
+}
+export default DayViewRenderer;

package/types/renderers/MonthViewRenderer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * MonthViewRenderer - Renders month calendar grid
+ *
+ * Pure JavaScript renderer for month view, compatible with Salesforce Locker Service.
+ */
+import { BaseViewRenderer } from './BaseViewRenderer.js';
+export declare class MonthViewRenderer extends BaseViewRenderer {
+    maxEventsToShow: number;
+    _pendingFocusMs: number | null | undefined;
+    _dayLabelFormatter: Intl.DateTimeFormat | undefined;
+    constructor(container: any, stateManager: any);
+    render(): void;
+    _renderMonthView(viewData: any, config: any): string;
+    _getDayNames(weekStartsOn: any): string[];
+    _renderWeek(week: any): string;
+    _renderDay(day: any): string;
+    _renderEvent(event: any): string;
+    _attachEventHandlers(): void;
+    /**
+     * Ensure exactly one grid cell participates in the tab order.
+     * Priority: requested focus date, selected date, today, first day of
+     * the current month.
+     * @param {number|null} focusMs - Preferred focus date as a timestamp
+     * @returns {HTMLElement|null} The tabbable cell
+     */
+    _applyRovingTabindex(focusMs?: number | null): HTMLElement | null;
+}
+export default MonthViewRenderer;

package/types/renderers/WeekViewRenderer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * WeekViewRenderer - Renders week calendar view
+ *
+ * Pure JavaScript renderer for week view, compatible with Salesforce Locker Service.
+ */
+import { BaseViewRenderer } from './BaseViewRenderer.js';
+export declare class WeekViewRenderer extends BaseViewRenderer {
+    hourHeight: number;
+    totalHeight: number;
+    constructor(container: any, stateManager: any);
+    render(): void;
+    _renderWeekView(viewData: any, _config: any): string;
+    _renderHeader(days: any): string;
+    _renderAllDayRow(days: any): string;
+    _renderTimeGrid(days: any, hours: any): string;
+    _renderTimeGutter(hours: any): string;
+    _renderDayColumn(day: any, hours: any): string;
+    _attachEventHandlers(): void;
+    _scrollToCurrentTime(): void;
+}
+export default WeekViewRenderer;

package/types/renderers/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * View Renderers
+ *
+ * Pure JavaScript renderers for calendar views.
+ * Compatible with Salesforce Locker Service (no custom elements).
+ */
+export { BaseViewRenderer } from './BaseViewRenderer.js';
+export { MonthViewRenderer } from './MonthViewRenderer.js';
+export { WeekViewRenderer } from './WeekViewRenderer.js';
+export { DayViewRenderer } from './DayViewRenderer.js';

package/types/utils/DOMUtils.d.ts

@@ -0,0 +1,121 @@
+/**
+ * DOMUtils - DOM manipulation and event utilities
+ */
+export declare class DOMUtils {
+    /**
+     * Create element with attributes and children
+     */
+    static createElement(tag: any, attributes?: {}, children?: any[]): any;
+    /**
+     * Add multiple event listeners
+     */
+    static addEventListeners(element: any, events: any): () => void;
+    /**
+     * Delegate event handling
+     */
+    static delegate(element: any, selector: any, event: any, handler: any): () => any;
+    /**
+     * Get element position relative to viewport
+     */
+    static getPosition(element: any): {
+        top: any;
+        left: any;
+        bottom: any;
+        right: any;
+        width: any;
+        height: any;
+    };
+    /**
+     * Check if element is in viewport
+     */
+    static isInViewport(element: any, threshold?: number): boolean;
+    /**
+     * Smooth scroll to element
+     */
+    static scrollToElement(element: any, options?: {}): void;
+    /**
+     * Get computed style value
+     */
+    static getStyle(element: any, property: any): string;
+    /**
+     * Set multiple styles
+     */
+    static setStyles(element: any, styles: any): void;
+    /**
+     * Add/remove classes with animation support
+     */
+    static animateClass(element: any, className: any, duration?: number): Promise<void>;
+    /**
+     * Wait for animation/transition to complete
+     * Resolves after `timeout` ms even if the event never fires (animation
+     * cancelled, element removed from DOM, etc.) so awaiting callers can't hang.
+     * @param {Element} element - Element to listen on
+     * @param {string} [eventType='animationend'] - Event to wait for
+     * @param {number} [timeout=3000] - Max wait in ms; 0 disables the timeout
+     */
+    static waitForAnimation(element: Element, eventType?: string, timeout?: number): Promise<any>;
+    /**
+     * Utility wait function
+     */
+    static wait(ms: any): Promise<any>;
+    /**
+     * Parse HTML string safely
+     * Sanitizes by default: strips script-capable elements, inline event
+     * handlers and javascript: URLs so the returned node is inert even if the
+     * input contains an XSS payload. Pass { sanitize: false } only for trusted,
+     * non-user-controlled markup.
+     */
+    static parseHTML(htmlString: any, { sanitize }?: {
+        sanitize?: boolean | undefined;
+    }): ChildNode | null;
+    /**
+     * Remove script-capable elements, on* handlers and javascript: URLs
+     * from a parsed DOM fragment (in place)
+     */
+    static _sanitizeNode(root: any): void;
+    /**
+     * Escape HTML to prevent XSS
+     */
+    static escapeHTML(str: any): string;
+    /**
+     * Debounce function calls
+     */
+    static debounce(func: any, wait?: number): (...args: any[]) => void;
+    /**
+     * Throttle function calls
+     */
+    static throttle(func: any, limit?: number): (...args: any[]) => void;
+    /**
+     * Get closest parent matching selector
+     */
+    static closest(element: any, selector: any): any;
+    /**
+     * Get all parents matching selector
+     */
+    static parents(element: any, selector: any): any[];
+    /**
+     * Measure element dimensions including margins
+     */
+    static getOuterDimensions(element: any): {
+        width: any;
+        height: any;
+        margin: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    /**
+     * Clone an element. Event listeners are NOT copied — the Web Platform
+     * provides no way to enumerate listeners, so callers must re-attach their
+     * own handlers to the clone.
+     * @deprecated Use element.cloneNode(deep) directly and re-bind listeners.
+     */
+    static cloneWithEvents(element: any, deep?: boolean): any;
+    /**
+     * Focus trap for modals/dialogs
+     */
+    static trapFocus(container: any): () => any;
+}
+export default DOMUtils;

package/types/utils/DateUtils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * DateUtils - Date formatting and manipulation utilities
+ *
+ * Extends Core DateUtils with UI-specific formatting
+ */
+import { DateUtils as CoreDateUtils } from '@forcecalendar/core';
+export declare class DateUtils extends CoreDateUtils {
+    /**
+     * Format date for display
+     */
+    static formatDate(date: any, format?: string, locale?: string): string;
+    /**
+     * Format time for display
+     */
+    static formatTime(date: any, showMinutes?: boolean, use24Hour?: boolean, locale?: string): string;
+    /**
+     * Format date range for display
+     */
+    static formatDateRange(start: any, end: any, locale?: string): string;
+    /**
+     * Format time range for display
+     */
+    static formatTimeRange(start: any, end: any, locale?: string): string;
+    /**
+     * Get relative time string (e.g., "2 hours ago", "in 3 days")
+     */
+    static getRelativeTime(date: any, baseDate?: Date, locale?: string): string;
+    /**
+     * Check if date is today
+     */
+    static isToday(date: any): any;
+    /**
+     * Check if date is in the past
+     */
+    static isPast(date: any): boolean;
+    /**
+     * Check if date is in the future
+     */
+    static isFuture(date: any): boolean;
+    /**
+     * Get calendar week number
+     */
+    static getWeekNumber(date: any): number;
+    /**
+     * Get day abbreviation
+     */
+    static getDayAbbreviation(dayIndex: any, locale?: string): string;
+    /**
+     * Get full day name
+     */
+    static getDayName(dayIndex: any, locale?: string): string;
+    /**
+     * Get month name
+     */
+    static getMonthName(monthIndex: any, format?: string, locale?: string): string;
+    /**
+     * Parse time string (e.g., "14:30" or "2:30 PM")
+     */
+    static parseTimeString(timeStr: any, baseDate?: Date): Date;
+}
+export default DateUtils;

package/types/utils/StyleUtils.d.ts

@@ -0,0 +1,146 @@
+/**
+ * StyleUtils - Styling utilities and theme management
+ */
+export declare class StyleUtils {
+    /**
+     * Default theme colors
+     */
+    static colors: {
+        primary: string;
+        secondary: string;
+        accent: string;
+        danger: string;
+        warning: string;
+        info: string;
+        success: string;
+        light: string;
+        dark: string;
+        white: string;
+        gray: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+    };
+    /**
+     * Common CSS variables
+     */
+    static cssVariables: {
+        '--fc-primary-color': string;
+        '--fc-primary-hover': string;
+        '--fc-primary-light': 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-accent-color': string;
+        '--fc-danger-color': string;
+        '--fc-success-color': string;
+        '--fc-font-family': string;
+        '--fc-font-size-xs': string;
+        '--fc-font-size-sm': string;
+        '--fc-font-size-base': string;
+        '--fc-font-size-lg': string;
+        '--fc-font-size-xl': string;
+        '--fc-font-size-2xl': string;
+        '--fc-line-height': string;
+        '--fc-font-weight-normal': string;
+        '--fc-font-weight-medium': string;
+        '--fc-font-weight-semibold': string;
+        '--fc-font-weight-bold': string;
+        '--fc-spacing-xs': string;
+        '--fc-spacing-sm': string;
+        '--fc-spacing-md': string;
+        '--fc-spacing-lg': string;
+        '--fc-spacing-xl': string;
+        '--fc-spacing-2xl': string;
+        '--fc-border-width': string;
+        '--fc-border-radius-sm': string;
+        '--fc-border-radius': string;
+        '--fc-border-radius-lg': string;
+        '--fc-border-radius-full': string;
+        '--fc-shadow-sm': string;
+        '--fc-shadow': string;
+        '--fc-shadow-md': string;
+        '--fc-shadow-lg': string;
+        '--fc-transition-fast': string;
+        '--fc-transition': string;
+        '--fc-transition-slow': string;
+        '--fc-z-dropdown': string;
+        '--fc-z-modal': string;
+        '--fc-z-tooltip': string;
+    };
+    /**
+     * Get CSS variable value
+     */
+    static getCSSVariable(name: any, element?: HTMLElement): string;
+    /**
+     * Set CSS variables
+     */
+    static setCSSVariables(variables: any, element?: HTMLElement): void;
+    /**
+     * Generate base styles
+     */
+    static getBaseStyles(): string;
+    /**
+     * Generate button styles
+     */
+    static getButtonStyles(): string;
+    /**
+     * Darken color by percentage
+     */
+    static darken(color: any, percent: any): string;
+    /**
+     * Lighten color by percentage
+     */
+    static lighten(color: any, percent: any): string;
+    /**
+     * Get contrast color (black or white) for background
+     */
+    static getContrastColor(bgColor: any): "#000000" | "#FFFFFF";
+    /**
+     * Sanitize color value to prevent CSS injection
+     * Returns the color if valid, or a fallback color if invalid
+     */
+    static sanitizeColor(color: any, fallback?: string): string;
+    /**
+     * Convert hex to rgba
+     */
+    static hexToRgba(hex: any, alpha?: number): string;
+    /**
+     * Generate grid styles
+     */
+    static getGridStyles(): string;
+    /**
+     * Get responsive breakpoints
+     */
+    static breakpoints: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+    };
+    /**
+     * Generate media query
+     */
+    static mediaQuery(breakpoint: any, styles: any): string;
+    /**
+     * Animation keyframes
+     */
+    static getAnimations(): string;
+}
+export default StyleUtils;