@forcecalendar/interface 1.1.0 → 1.3.0

package/types/renderers/BaseViewRenderer.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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;
+    _pendingSlotFocus: {
+        colIndex: number;
+        hour: number;
+    } | {
+        colIndex: number;
+        hour: number;
+    } | null | undefined;
+    /**
+     * @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;
+    /**
+     * WAI-ARIA semantics and keyboard navigation for time grids (week/day
+     * views). The DOM is column-major (a column per day, an hour line per
+     * slot), so each day column is exposed as a row of 24 hour gridcells.
+     * Arrow keys navigate visually: Up/Down moves hours, Left/Right moves
+     * days, Home/End jumps to the day's bounds, PageUp/PageDown navigates
+     * periods, Enter/Space selects the slot's date and time.
+     * @param {string} columnSelector - Selector for the day columns
+     * @param {string} gridLabel - Accessible label for the grid
+     */
+    _enhanceTimeGridAccessibility(columnSelector: string, gridLabel: string): void;
+    /**
+     * Get the hour slot at a column/hour position
+     * @private
+     */
+    private _slotAt;
+    /**
+     * Keep exactly one hour slot tabbable. Defaults to 9:00 AM in the
+     * first column (today's column when present).
+     * @private
+     */
+    private _applySlotRovingTabindex;
+    /**
+     * 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;