Calendar/docs/date-mode-initialization-sequence.md

Calendar Plantempus - Date Mode Initialization Sequence

Overview

This document shows the complete initialization sequence and event flow for Date Mode in Calendar Plantempus, including when data is loaded and ready for rendering.

Sequence Diagram

sequenceDiagram
    participant Browser as Browser
    participant Index as index.ts
    participant Config as CalendarConfig
    participant Factory as CalendarTypeFactory
    participant CM as CalendarManager
    participant EM as EventManager
    participant GM as GridManager
    participant NM as NavigationManager
    participant VM as ViewManager
    participant ER as EventRenderer
    participant SM as ScrollManager
    participant EB as EventBus
    participant DOM as DOM

    Note over Browser: Page loads calendar application
    Browser->>Index: Load application

    Note over Index: PHASE 0: Pre-initialization Setup
    Index->>Config: new CalendarConfig()
    Config->>Config: loadCalendarType() - Read URL ?type=date
    Config->>Config: loadFromDOM() - Read data attributes
    Config->>Config: Set mode='date', period='week'

    Index->>Factory: CalendarTypeFactory.initialize()
    Factory->>Factory: Create DateHeaderRenderer
    Factory->>Factory: Create DateColumnRenderer  
    Factory->>Factory: Create DateEventRenderer
    Note over Factory: Strategy Pattern renderers ready

    Note over Index: PHASE 1: Core Managers Construction
    Index->>CM: new CalendarManager(eventBus, config)
    CM->>EB: Subscribe to VIEW_CHANGE_REQUESTED
    CM->>EB: Subscribe to NAV_PREV, NAV_NEXT

    Index->>NM: new NavigationManager(eventBus)
    NM->>EB: Subscribe to CALENDAR_INITIALIZED
    Note over NM: Will wait to call updateWeekInfo()

    Index->>VM: new ViewManager(eventBus)
    VM->>EB: Subscribe to CALENDAR_INITIALIZED

    Note over Index: PHASE 2: Data & Rendering Managers
    Index->>EM: new EventManager(eventBus)
    EM->>EB: Subscribe to CALENDAR_INITIALIZED
    Note over EM: Will wait to load data

    Index->>ER: new EventRenderer(eventBus)
    ER->>EB: Subscribe to EVENTS_LOADED
    ER->>EB: Subscribe to GRID_RENDERED
    Note over ER: Needs BOTH events before rendering

    Note over Index: PHASE 3: Layout Managers (Order Critical!)
    Index->>SM: new ScrollManager()
    SM->>EB: Subscribe to GRID_RENDERED
    Note over SM: Must subscribe BEFORE GridManager renders

    Index->>GM: new GridManager()
    GM->>EB: Subscribe to CALENDAR_INITIALIZED
    GM->>EB: Subscribe to CALENDAR_DATA_LOADED
    GM->>GM: Set currentWeek = getWeekStart(new Date())
    Note over GM: Ready to render, but waiting

    Note over Index: PHASE 4: Coordinated Initialization
    Index->>CM: initialize()
    
    CM->>EB: emit(CALENDAR_INITIALIZING)
    CM->>CM: setView('week'), setCurrentDate()
    CM->>EB: emit(CALENDAR_INITIALIZED) ⭐
    
    Note over EB: 🚀 CALENDAR_INITIALIZED triggers all managers

    par EventManager Data Loading
        EB->>EM: CALENDAR_INITIALIZED
        EM->>EM: loadMockData() for date mode
        EM->>EM: fetch('/src/data/mock-events.json')
        Note over EM: Loading date-specific mock data
        EM->>EM: Process events for current week
        EM->>EB: emit(CALENDAR_DATA_LOADED, {calendarType: 'date', data})
        EM->>EB: emit(EVENTS_LOADED, {events: [...])
    
    and GridManager Initial Rendering
        EB->>GM: CALENDAR_INITIALIZED
        GM->>GM: render()
        GM->>GM: updateGridStyles() - Set --grid-columns: 7
        GM->>GM: createHeaderSpacer()
        GM->>GM: createTimeAxis(dayStartHour, dayEndHour)
        GM->>GM: createGridContainer()
        
        Note over GM: Strategy Pattern - Date Mode Rendering
        GM->>Factory: getHeaderRenderer('date') → DateHeaderRenderer
        GM->>GM: renderCalendarHeader() - Create day headers
        GM->>DOM: Create 7 swp-day-column elements
        
        GM->>Factory: getColumnRenderer('date') → DateColumnRenderer  
        GM->>GM: renderColumnContainer() - Date columns
        GM->>EB: emit(GRID_RENDERED) ⭐
    
    and NavigationManager UI
        EB->>NM: CALENDAR_INITIALIZED
        NM->>NM: updateWeekInfo()
        NM->>DOM: Update week display in navigation
        NM->>EB: emit(WEEK_INFO_UPDATED)
    
    and ViewManager Setup
        EB->>VM: CALENDAR_INITIALIZED
        VM->>VM: initializeView()
        VM->>EB: emit(VIEW_RENDERED)
    end

    Note over GM: GridManager receives its own data event
    EB->>GM: CALENDAR_DATA_LOADED
    GM->>GM: updateGridStyles() - Recalculate columns if needed
    Note over GM: Grid already rendered, just update styles

    Note over ER: 🎯 Critical Synchronization Point
    EB->>ER: EVENTS_LOADED
    ER->>ER: pendingEvents = events (store, don't render yet)
    Note over ER: Waiting for grid to be ready...

    EB->>ER: GRID_RENDERED  
    ER->>DOM: querySelectorAll('swp-day-column') - Check if ready
    DOM-->>ER: Return 7 day columns (ready!)
    
    Note over ER: Both events loaded AND grid ready → Render!
    ER->>Factory: getEventRenderer('date') → DateEventRenderer
    ER->>ER: renderEvents(pendingEvents) using DateEventRenderer
    ER->>DOM: Position events in day columns
    ER->>ER: Clear pendingEvents
    ER->>EB: emit(EVENT_RENDERED)

    Note over SM: ScrollManager sets up after grid is complete
    EB->>SM: GRID_RENDERED
    SM->>DOM: querySelector('swp-scrollable-content')
    SM->>SM: setupScrolling()
    SM->>SM: applyScrollbarStyling()
    SM->>SM: setupScrollSynchronization()

    Note over Index: 🎊 Date Mode Initialization Complete!
    Note over Index: Ready for user interaction

Key Initialization Phases

Phase 0: Pre-initialization Setup

• CalendarConfig: Loads URL parameters (?type=date) and DOM attributes
• CalendarTypeFactory: Creates strategy pattern renderers for date mode

Phase 1: Core Managers Construction

• CalendarManager: Central coordinator
• NavigationManager: Week navigation controls
• ViewManager: View state management

Phase 2: Data & Rendering Managers

• EventManager: Handles data loading
• EventRenderer: Manages event display with synchronization

Phase 3: Layout Managers (Order Critical!)

• ScrollManager: Must subscribe before GridManager renders
• GridManager: Main grid rendering

Phase 4: Coordinated Initialization

• CalendarManager.initialize(): Triggers CALENDAR_INITIALIZED event
• All managers respond simultaneously but safely

Critical Synchronization Points

1. Event-Grid Synchronization

// EventRenderer waits for BOTH events
if (this.pendingEvents.length > 0) {
    const columns = document.querySelectorAll('swp-day-column'); // DATE MODE
    if (columns.length > 0) { // Grid must exist first
        this.renderEvents(this.pendingEvents);
    }
}

2. Scroll-Grid Dependency

// ScrollManager only sets up after grid is rendered
eventBus.on(EventTypes.GRID_RENDERED, () => {
    this.setupScrolling(); // Safe to access DOM now
});

3. Manager Construction Order

// Critical order: ScrollManager subscribes BEFORE GridManager renders
const scrollManager = new ScrollManager(); 
const gridManager = new GridManager();

Date Mode Specifics

Data Loading

• Uses /src/data/mock-events.json
• Processes events for current week
• Emits CALENDAR_DATA_LOADED with calendarType: 'date'

Grid Rendering

• Creates 7 swp-day-column elements (weekDays: 7)
• Uses DateHeaderRenderer strategy
• Uses DateColumnRenderer strategy
• Sets --grid-columns: 7 CSS variable

Event Rendering

• Uses DateEventRenderer strategy
• Positions events in day columns based on start/end time
• Calculates pixel positions using PositionUtils

Race Condition Prevention

1. Subscription Before Action: All managers subscribe during construction, act on CALENDAR_INITIALIZED
2. DOM Existence Checks: Managers verify DOM elements exist before manipulation
3. Event Ordering: GRID_RENDERED always fires before event rendering attempts
4. Pending States: EventRenderer stores pending events until grid is ready
5. Coordinated Start: Single CALENDAR_INITIALIZED event starts all processes

Debugging Points

Key events to monitor during initialization:

• CALENDAR_INITIALIZED - Start of coordinated setup
• CALENDAR_DATA_LOADED - Date data ready
• GRID_RENDERED - Grid structure complete
• EVENTS_LOADED - Event data ready
• EVENT_RENDERED - Events positioned in grid

This sequence ensures deterministic, race-condition-free initialization with comprehensive logging for debugging.