@forcecalendar/interface 1.1.0 → 1.3.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@forcecalendar/interface",
-  "version": "1.1.0",
+  "version": "1.3.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/src/components/ForceCalendar.js

@@ -397,6 +397,7 @@ export class ForceCalendar extends BaseComponent {
             }
 
             .fc-month-day:focus-visible,
+            .fc-hour-slot:focus-visible,
             .fc-event:focus-visible {
                 outline: 2px solid var(--fc-primary-color);
                 outline-offset: -2px;

package/src/renderers/BaseViewRenderer.js

@@ -329,6 +329,146 @@ export class BaseViewRenderer {
     }
   }
 
+  /**
+   * 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, gridLabel) {
+    const grid = this.container.querySelector('.fc-time-grid');
+    if (!grid) return;
+    grid.setAttribute('role', 'grid');
+    grid.setAttribute('aria-label', gridLabel);
+    const gutter = this.container.querySelector('.fc-time-gutter');
+    if (gutter) gutter.setAttribute('aria-hidden', 'true');
+
+    const locale = this.stateManager.getState().config.locale || 'en-US';
+    const dayFormatter = new Intl.DateTimeFormat(locale, {
+      weekday: 'long',
+      month: 'long',
+      day: 'numeric'
+    });
+
+    const columns = Array.from(this.container.querySelectorAll(columnSelector));
+    for (const col of columns) {
+      col.setAttribute('role', 'row');
+      const colDate = new Date(col.dataset.date);
+      const colLabel = dayFormatter.format(colDate);
+      col.setAttribute('aria-label', colLabel);
+      for (const slot of col.querySelectorAll('.fc-hour-slot')) {
+        slot.setAttribute('role', 'gridcell');
+        slot.setAttribute('tabindex', '-1');
+        slot.setAttribute(
+          'aria-label',
+          `${colLabel}, ${this.formatHour(Number(slot.dataset.hour))}`
+        );
+      }
+    }
+
+    this._applySlotRovingTabindex(columns);
+
+    if (this._pendingSlotFocus) {
+      const { colIndex, hour } = this._pendingSlotFocus;
+      this._pendingSlotFocus = null;
+      const target = this._slotAt(columns, colIndex, hour);
+      if (target) {
+        this._applySlotRovingTabindex(columns, target);
+        target.focus();
+      }
+    }
+
+    this.addListener(this.container, 'keydown', e => {
+      const slot = e.target.closest('.fc-hour-slot');
+      if (!slot || !this.container.contains(slot)) return;
+      const col = slot.closest(columnSelector);
+      const colIndex = columns.indexOf(col);
+      const hour = Number(slot.dataset.hour);
+      let target = null;
+
+      switch (e.key) {
+        case 'ArrowDown':
+          target = this._slotAt(columns, colIndex, hour + 1);
+          break;
+        case 'ArrowUp':
+          target = this._slotAt(columns, colIndex, hour - 1);
+          break;
+        case 'ArrowRight':
+          target = this._slotAt(columns, colIndex + 1, hour);
+          break;
+        case 'ArrowLeft':
+          target = this._slotAt(columns, colIndex - 1, hour);
+          break;
+        case 'Home':
+          target = this._slotAt(columns, colIndex, 0);
+          break;
+        case 'End':
+          target = this._slotAt(columns, colIndex, 23);
+          break;
+        case 'PageUp':
+        case 'PageDown':
+          e.preventDefault();
+          this._pendingSlotFocus = { colIndex, hour };
+          if (e.key === 'PageDown') {
+            this.stateManager.next();
+          } else {
+            this.stateManager.previous();
+          }
+          return;
+        case 'Enter':
+        case ' ': {
+          e.preventDefault();
+          const date = new Date(col.dataset.date);
+          date.setHours(hour, 0, 0, 0);
+          this._pendingSlotFocus = { colIndex, hour };
+          this.stateManager.selectDate(date);
+          return;
+        }
+        default:
+          return;
+      }
+
+      e.preventDefault();
+      if (target) {
+        this._applySlotRovingTabindex(columns, target);
+        target.scrollIntoView?.({ block: 'nearest' });
+        target.focus();
+      }
+    });
+  }
+
+  /**
+   * Get the hour slot at a column/hour position
+   * @private
+   */
+  _slotAt(columns, colIndex, hour) {
+    if (colIndex < 0 || colIndex >= columns.length || hour < 0 || hour > 23) return null;
+    return columns[colIndex].querySelector(`.fc-hour-slot[data-hour="${hour}"]`);
+  }
+
+  /**
+   * Keep exactly one hour slot tabbable. Defaults to 9:00 AM in the
+   * first column (today's column when present).
+   * @private
+   */
+  _applySlotRovingTabindex(columns, active = null) {
+    const slots = this.container.querySelectorAll('.fc-hour-slot');
+    if (slots.length === 0) return;
+    if (!active) {
+      const todayCol =
+        columns.find(c => this.isToday(new Date(c.dataset.date))) || columns[0];
+      active = todayCol && todayCol.querySelector('.fc-hour-slot[data-hour="9"]');
+      active = active || slots[0];
+    }
+    for (const s of slots) {
+      s.setAttribute('tabindex', s === active ? '0' : '-1');
+    }
+  }
+
   /**
    * Make rendered events keyboard-reachable and screen-reader labeled.
    * Runs after every render, across all views.

package/src/renderers/DayViewRenderer.js

@@ -165,7 +165,7 @@ export class DayViewRenderer extends BaseViewRenderer {
     return `
             <div class="fc-day-column" data-date="${dayDate.toISOString()}" style="position: relative; cursor: pointer;">
                 <!-- Hour grid lines -->
-                ${hours.map(() => `<div style="height: ${this.hourHeight}px; border-bottom: 1px solid var(--fc-background-hover);"></div>`).join('')}
+                ${hours.map(h => `<div class="fc-hour-slot" data-hour="${h}" style="height: ${this.hourHeight}px; border-bottom: 1px solid var(--fc-background-hover);"></div>`).join('')}
 
                 <!-- Now indicator for today -->
                 ${isToday ? this.renderNowIndicator() : ''}
@@ -211,6 +211,11 @@ export class DayViewRenderer extends BaseViewRenderer {
 
     // Common event handlers (event clicks)
     this.attachCommonEventHandlers();
+
+    const locale = this.stateManager.getState().config.locale || 'en-US';
+    const current = this.stateManager.getState().currentDate || new Date();
+    const label = new Intl.DateTimeFormat(locale, { weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' }).format(current);
+    this._enhanceTimeGridAccessibility('.fc-day-column', label);
   }
 
   _scrollToCurrentTime() {

package/src/renderers/WeekViewRenderer.js

@@ -144,7 +144,7 @@ export class WeekViewRenderer extends BaseViewRenderer {
     return `
             <div class="fc-week-day-column" data-date="${day.date.toISOString()}" style="border-right: 1px solid var(--fc-border-color); position: relative; cursor: pointer;">
                 <!-- Hour grid lines -->
-                ${hours.map(() => `<div style="height: ${this.hourHeight}px; border-bottom: 1px solid var(--fc-background-hover);"></div>`).join('')}
+                ${hours.map(h => `<div class="fc-hour-slot" data-hour="${h}" style="height: ${this.hourHeight}px; border-bottom: 1px solid var(--fc-background-hover);"></div>`).join('')}
 
                 <!-- Now indicator for today -->
                 ${day.isToday ? this.renderNowIndicator() : ''}
@@ -190,6 +190,12 @@ export class WeekViewRenderer extends BaseViewRenderer {
 
     // Common event handlers (event clicks)
     this.attachCommonEventHandlers();
+
+    const days = this.stateManager.getViewData()?.days || [];
+    const locale = this.stateManager.getState().config.locale || 'en-US';
+    const first = days[0] ? new Date(days[0].date) : new Date();
+    const label = `Week of ${new Intl.DateTimeFormat(locale, { month: 'long', day: 'numeric', year: 'numeric' }).format(first)}`;
+    this._enhanceTimeGridAccessibility('.fc-week-day-column', label);
   }
 
   _scrollToCurrentTime() {

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';