@forcecalendar/interface 1.0.61 → 1.2.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@forcecalendar/interface",
-  "version": "1.0.61",
+  "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",
-    "vite": "^5.0.0"
-  }
+    "typescript": "^7.0.2",
+    "vite": "^8.1.4"
+  },
+  "types": "./types/index.d.ts"
 }

package/src/components/ForceCalendar.js

@@ -396,6 +396,20 @@ export class ForceCalendar extends BaseComponent {
                 padding: 0;
             }
 
+            .fc-month-day:focus-visible,
+            .fc-event:focus-visible {
+                outline: 2px solid var(--fc-primary-color);
+                outline-offset: -2px;
+            }
+
+            .fc-nav-arrow:focus-visible,
+            .fc-btn:focus-visible,
+            .fc-btn-today:focus-visible,
+            .fc-view-button:focus-visible {
+                outline: 2px solid var(--fc-primary-color);
+                outline-offset: 2px;
+            }
+
             .fc-nav-arrow:hover {
                 background: var(--fc-background-hover);
                 color: var(--fc-text-color);
@@ -705,11 +719,11 @@ export class ForceCalendar extends BaseComponent {
                     </div>
 
                     <div class="fc-header-center">
-                        <button class="fc-nav-arrow" data-action="previous" title="Previous">
+                        <button class="fc-nav-arrow" data-action="previous" title="Previous" aria-label="Previous ${view}">
                             ${this.getIcon('chevron-left')}
                         </button>
-                        <h2 class="fc-title">${DOMUtils.escapeHTML(title)}</h2>
-                        <button class="fc-nav-arrow" data-action="next" title="Next">
+                        <h2 class="fc-title" aria-live="polite">${DOMUtils.escapeHTML(title)}</h2>
+                        <button class="fc-nav-arrow" data-action="next" title="Next" aria-label="Next ${view}">
                             ${this.getIcon('chevron-right')}
                         </button>
                     </div>
@@ -718,12 +732,15 @@ export class ForceCalendar extends BaseComponent {
                         <button class="fc-btn fc-btn-primary" id="create-event-btn" style="height: 28px; padding: 0 12px; font-size: 12px;">
                             + New Event
                         </button>
-                        <div class="fc-view-buttons" role="group">
+                        <div class="fc-view-buttons" role="group" aria-label="Calendar view">
                             <button class="fc-view-button ${view === 'month' ? 'active' : ''}"
+                                    aria-pressed="${view === 'month' ? 'true' : 'false'}"
                                     data-view="month">Month</button>
                             <button class="fc-view-button ${view === 'week' ? 'active' : ''}"
+                                    aria-pressed="${view === 'week' ? 'true' : 'false'}"
                                     data-view="week">Week</button>
                             <button class="fc-view-button ${view === 'day' ? 'active' : ''}"
+                                    aria-pressed="${view === 'day' ? 'true' : 'false'}"
                                     data-view="day">Day</button>
                         </div>
                     </div>

package/src/renderers/BaseViewRenderer.js

@@ -304,12 +304,46 @@ export class BaseViewRenderer {
       if (!eventEl || !this.container.contains(eventEl)) return;
 
       e.stopPropagation();
-      const eventId = eventEl.dataset.eventId;
-      const event = this.stateManager.getEvents().find(ev => ev.id === eventId);
-      if (event) {
-        this.stateManager.selectEvent(event);
-      }
+      this._selectEventFromElement(eventEl);
     });
+
+    // Keyboard activation for events (Enter / Space)
+    this.addListener(this.container, 'keydown', e => {
+      if (e.key !== 'Enter' && e.key !== ' ') return;
+      const eventEl = e.target.closest('.fc-event');
+      if (!eventEl || !this.container.contains(eventEl)) return;
+
+      e.preventDefault();
+      e.stopPropagation();
+      this._selectEventFromElement(eventEl);
+    });
+
+    this._enhanceEventAccessibility();
+  }
+
+  _selectEventFromElement(eventEl) {
+    const eventId = eventEl.dataset.eventId;
+    const event = this.stateManager.getEvents().find(ev => ev.id === eventId);
+    if (event) {
+      this.stateManager.selectEvent(event);
+    }
+  }
+
+  /**
+   * Make rendered events keyboard-reachable and screen-reader labeled.
+   * Runs after every render, across all views.
+   */
+  _enhanceEventAccessibility() {
+    for (const el of this.container.querySelectorAll('.fc-event')) {
+      el.setAttribute('role', 'button');
+      el.setAttribute('tabindex', '0');
+      if (!el.hasAttribute('aria-label')) {
+        const label = (el.getAttribute('title') || el.textContent || '').trim();
+        if (label) {
+          el.setAttribute('aria-label', `Event: ${label}`);
+        }
+      }
+    }
   }
 }
 

package/src/renderers/MonthViewRenderer.js

@@ -28,16 +28,37 @@ export class MonthViewRenderer extends BaseViewRenderer {
     const html = this._renderMonthView(viewData, config);
     this.container.innerHTML = html;
     this._attachEventHandlers();
+
+    // Roving tabindex: exactly one cell is tabbable; restore focus after
+    // a keyboard-initiated re-render (month navigation, selection)
+    const active = this._applyRovingTabindex(this._pendingFocusMs ?? null);
+    if (this._pendingFocusMs != null) {
+      this._pendingFocusMs = null;
+      if (active) {
+        active.focus();
+      }
+    }
   }
 
   _renderMonthView(viewData, config) {
     const weekStartsOn = config.weekStartsOn || 0;
     const dayNames = this._getDayNames(weekStartsOn);
+    const locale = config.locale || 'en-US';
+    this._dayLabelFormatter = new Intl.DateTimeFormat(locale, {
+      weekday: 'long',
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric'
+    });
+    const currentDate = this.stateManager.getState().currentDate;
+    const gridLabel = new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(
+      currentDate || new Date()
+    );
 
     let html = `
-            <div class="fc-month-view" style="display: flex; flex-direction: column; height: 100%; min-height: 400px; background: var(--fc-background); border: 1px solid var(--fc-border-color);">
-                <div class="fc-month-header" style="display: grid; grid-template-columns: repeat(7, 1fr); border-bottom: 1px solid var(--fc-border-color); background: var(--fc-background-alt);">
-                    ${dayNames.map(d => `<div class="fc-month-header-cell" style="padding: 12px 8px; text-align: center; font-size: 11px; font-weight: 600; color: var(--fc-text-light); text-transform: uppercase;">${this.escapeHTML(d)}</div>`).join('')}
+            <div class="fc-month-view" role="grid" aria-label="${this.escapeHTML(gridLabel)}" style="display: flex; flex-direction: column; height: 100%; min-height: 400px; background: var(--fc-background); border: 1px solid var(--fc-border-color);">
+                <div class="fc-month-header" role="row" style="display: grid; grid-template-columns: repeat(7, 1fr); border-bottom: 1px solid var(--fc-border-color); background: var(--fc-background-alt);">
+                    ${dayNames.map(d => `<div class="fc-month-header-cell" role="columnheader" style="padding: 12px 8px; text-align: center; font-size: 11px; font-weight: 600; color: var(--fc-text-light); text-transform: uppercase;">${this.escapeHTML(d)}</div>`).join('')}
                 </div>
                 <div class="fc-month-body" style="display: flex; flex-direction: column; flex: 1;">
         `;
@@ -62,7 +83,7 @@ export class MonthViewRenderer extends BaseViewRenderer {
 
   _renderWeek(week) {
     let html =
-      '<div class="fc-month-week" style="display: grid; grid-template-columns: repeat(7, 1fr); flex: 1; min-height: 80px;">';
+      '<div class="fc-month-week" role="row" style="display: grid; grid-template-columns: repeat(7, 1fr); flex: 1; min-height: 80px;">';
 
     week.days.forEach(day => {
       html += this._renderDay(day);
@@ -86,8 +107,20 @@ export class MonthViewRenderer extends BaseViewRenderer {
     const visibleEvents = events.slice(0, this.maxEventsToShow);
     const moreCount = events.length - this.maxEventsToShow;
 
+    let cellLabel = this._dayLabelFormatter
+      ? this._dayLabelFormatter.format(new Date(day.date))
+      : day.date;
+    if (events.length > 0) {
+      cellLabel += `, ${events.length} ${events.length === 1 ? 'event' : 'events'}`;
+    }
+
     return `
             <div class="fc-month-day" data-date="${this.escapeHTML(day.date)}"
+                 role="gridcell" tabindex="-1"
+                 aria-selected="${day.isSelected ? 'true' : 'false'}"
+                 ${isToday ? 'aria-current="date"' : ''}
+                 ${isOtherMonth ? 'data-other-month="true"' : ''}
+                 aria-label="${this.escapeHTML(cellLabel)}"
                  style="background: ${dayBg}; border-right: 1px solid var(--fc-border-color); border-bottom: 1px solid var(--fc-border-color); padding: 4px; min-height: 80px; cursor: pointer; display: flex; flex-direction: column;">
                 <div class="fc-day-number" style="font-size: 13px; font-weight: 500; color: ${dayNumColor}; padding: 2px 4px; margin-bottom: 4px; ${todayStyle}">
                     ${this.escapeHTML(String(day.dayOfMonth))}
@@ -121,9 +154,112 @@ export class MonthViewRenderer extends BaseViewRenderer {
       this.stateManager.selectDate(date);
     });
 
+    // WAI-ARIA grid keyboard navigation
+    this.addListener(this.container, 'keydown', e => {
+      if (e.target.closest('.fc-event')) return; // events handle their own keys
+      const cell = e.target.closest('.fc-month-day');
+      if (!cell || !this.container.contains(cell)) return;
+
+      const cells = Array.from(this.container.querySelectorAll('.fc-month-day'));
+      const idx = cells.indexOf(cell);
+      let targetIdx;
+
+      switch (e.key) {
+        case 'ArrowRight':
+          targetIdx = idx + 1;
+          break;
+        case 'ArrowLeft':
+          targetIdx = idx - 1;
+          break;
+        case 'ArrowDown':
+          targetIdx = idx + 7;
+          break;
+        case 'ArrowUp':
+          targetIdx = idx - 7;
+          break;
+        case 'Home':
+          targetIdx = idx - (idx % 7);
+          break;
+        case 'End':
+          targetIdx = idx - (idx % 7) + 6;
+          break;
+        case 'PageUp':
+        case 'PageDown': {
+          e.preventDefault();
+          const d = new Date(cell.dataset.date);
+          d.setMonth(d.getMonth() + (e.key === 'PageDown' ? 1 : -1));
+          this._pendingFocusMs = d.getTime();
+          if (e.key === 'PageDown') {
+            this.stateManager.next();
+          } else {
+            this.stateManager.previous();
+          }
+          return;
+        }
+        case 'Enter':
+        case ' ': {
+          e.preventDefault();
+          const date = new Date(cell.dataset.date);
+          this._pendingFocusMs = date.getTime();
+          this.stateManager.selectDate(date);
+          return;
+        }
+        default:
+          return;
+      }
+
+      e.preventDefault();
+      if (targetIdx >= 0 && targetIdx < cells.length) {
+        this._applyRovingTabindex(new Date(cells[targetIdx].dataset.date).getTime());
+        cells[targetIdx].focus();
+      } else {
+        // Focus target falls outside the rendered grid: navigate and
+        // restore focus on the equivalent date after re-render
+        const d = new Date(cell.dataset.date);
+        d.setDate(d.getDate() + (targetIdx - idx));
+        this._pendingFocusMs = d.getTime();
+        if (targetIdx < 0) {
+          this.stateManager.previous();
+        } else {
+          this.stateManager.next();
+        }
+      }
+    });
+
     // Common event handlers (event clicks)
     this.attachCommonEventHandlers();
   }
+
+  /**
+   * 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 = null) {
+    const cells = Array.from(this.container.querySelectorAll('.fc-month-day'));
+    if (cells.length === 0) return null;
+
+    let active = null;
+    if (focusMs != null) {
+      active = cells.find(c => new Date(c.dataset.date).getTime() === focusMs);
+    }
+    if (!active) {
+      active = cells.find(c => c.getAttribute('aria-selected') === 'true');
+    }
+    if (!active) {
+      active = cells.find(c => c.hasAttribute('aria-current'));
+    }
+    if (!active) {
+      active = cells.find(c => !c.dataset.otherMonth) || cells[0];
+    }
+
+    for (const c of cells) {
+      c.setAttribute('tabindex', c === active ? '0' : '-1');
+    }
+    return active;
+  }
 }
 
 export default MonthViewRenderer;

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