Implements advanced event stacking and grid layout

Introduces a 3-phase algorithm in `EventStackManager` for dynamic event positioning. Groups events by start time proximity to determine optimal layout.

Optimizes horizontal space by using side-by-side grid columns for simultaneous events and allowing non-overlapping events to share stack levels. Supports nested stacking for late-arriving events within grid columns.

Includes comprehensive documentation (`STACKING_CONCEPT.md`) and a visual demonstration (`stacking-visualization.html`) to explain the new layout logic. Updates event rendering to utilize the new manager and adds extensive test coverage.

src/renderers/EventRenderer.ts

@@ -7,6 +7,7 @@ import { PositionUtils } from '../utils/PositionUtils';
 import { ColumnBounds } from '../utils/ColumnDetectionUtils';
 import { DragColumnChangeEventPayload, DragMoveEventPayload, DragStartEventPayload } from '../types/EventTypes';
 import { DateService } from '../utils/DateService';
+import { EventStackManager, EventGroup, StackLink } from '../managers/EventStackManager';
 
 /**
  * Interface for event rendering strategies
@@ -29,12 +30,14 @@ export interface EventRendererStrategy {
 export class DateEventRenderer implements EventRendererStrategy {
 
   private dateService: DateService;
+  private stackManager: EventStackManager;
   private draggedClone: HTMLElement | null = null;
   private originalEvent: HTMLElement | null = null;
 
   constructor() {
     const timezone = calendarConfig.getTimezone?.();
     this.dateService = new DateService(timezone);
+    this.stackManager = new EventStackManager();
   }
  
   private applyDragStyling(element: HTMLElement): void {
@@ -169,18 +172,177 @@ export class DateEventRenderer implements EventRendererStrategy {
 
     columns.forEach(column => {
       const columnEvents = this.getEventsForColumn(column, timedEvents);
-      const eventsLayer = column.querySelector('swp-events-layer');
-      
+      const eventsLayer = column.querySelector('swp-events-layer') as HTMLElement;
+
       if (eventsLayer) {
-        // Simply render each event - no overlap handling
-        columnEvents.forEach(event => {
-          const element = this.renderEvent(event);
-          eventsLayer.appendChild(element);
-        });
+        this.renderColumnEvents(columnEvents, eventsLayer);
       }
     });
   }
 
+  /**
+   * Render events in a column using combined stacking + grid algorithm
+   */
+  private renderColumnEvents(columnEvents: CalendarEvent[], eventsLayer: HTMLElement): void {
+    if (columnEvents.length === 0) return;
+
+    console.log('[EventRenderer] Rendering column with', columnEvents.length, 'events');
+
+    // Step 1: Calculate stack levels for ALL events first (to understand overlaps)
+    const allStackLinks = this.stackManager.createOptimizedStackLinks(columnEvents);
+
+    console.log('[EventRenderer] All stack links:');
+    columnEvents.forEach(event => {
+      const link = allStackLinks.get(event.id);
+      console.log(`  Event ${event.id} (${event.title}): stackLevel=${link?.stackLevel ?? 'none'}`);
+    });
+
+    // Step 2: Find grid candidates (start together ±15 min)
+    const groups = this.stackManager.groupEventsByStartTime(columnEvents);
+    const gridGroups = groups.filter(group => {
+      if (group.events.length <= 1) return false;
+      group.containerType = this.stackManager.decideContainerType(group);
+      return group.containerType === 'GRID';
+    });
+
+    console.log('[EventRenderer] Grid groups:', gridGroups.length);
+    gridGroups.forEach((g, i) => {
+      console.log(`  Grid group ${i}:`, g.events.map(e => e.id));
+    });
+
+    // Step 3: Render grid groups and track which events have been rendered
+    const renderedIds = new Set<string>();
+
+    gridGroups.forEach((group, index) => {
+      console.log(`[EventRenderer] Rendering grid group ${index} with ${group.events.length} events:`, group.events.map(e => e.id));
+
+      // Calculate grid group stack level by finding what it overlaps OUTSIDE the group
+      const gridStackLevel = this.calculateGridGroupStackLevel(group, columnEvents, allStackLinks);
+
+      console.log(`  Grid group stack level: ${gridStackLevel}`);
+
+      this.renderGridGroup(group, eventsLayer, gridStackLevel);
+      group.events.forEach(e => renderedIds.add(e.id));
+    });
+
+    // Step 4: Get remaining events (not in grid)
+    const remainingEvents = columnEvents.filter(e => !renderedIds.has(e.id));
+
+    console.log('[EventRenderer] Remaining events for stacking:');
+    remainingEvents.forEach(event => {
+      const link = allStackLinks.get(event.id);
+      console.log(`  Event ${event.id} (${event.title}): stackLevel=${link?.stackLevel ?? 'none'}`);
+    });
+
+    // Step 5: Render remaining stacked/single events
+    remainingEvents.forEach(event => {
+      const element = this.renderEvent(event);
+      const stackLink = allStackLinks.get(event.id);
+
+      console.log(`[EventRenderer] Rendering stacked event ${event.id}, stackLink:`, stackLink);
+
+      if (stackLink) {
+        // Apply stack link to element (for drag-drop)
+        this.stackManager.applyStackLinkToElement(element, stackLink);
+
+        // Apply visual styling
+        this.stackManager.applyVisualStyling(element, stackLink.stackLevel);
+        console.log(`  Applied margin-left: ${stackLink.stackLevel * 15}px, stack-link:`, stackLink);
+      }
+
+      eventsLayer.appendChild(element);
+    });
+  }
+
+
+  /**
+   * Calculate stack level for a grid group based on what it overlaps OUTSIDE the group
+   */
+  private calculateGridGroupStackLevel(
+    group: EventGroup,
+    allEvents: CalendarEvent[],
+    stackLinks: Map<string, StackLink>
+  ): number {
+    const groupEventIds = new Set(group.events.map(e => e.id));
+
+    // Find all events OUTSIDE this group
+    const outsideEvents = allEvents.filter(e => !groupEventIds.has(e.id));
+
+    // Find the highest stackLevel of any event that overlaps with ANY event in the grid group
+    let maxOverlappingLevel = -1;
+
+    for (const gridEvent of group.events) {
+      for (const outsideEvent of outsideEvents) {
+        if (this.stackManager.doEventsOverlap(gridEvent, outsideEvent)) {
+          const outsideLink = stackLinks.get(outsideEvent.id);
+          if (outsideLink) {
+            maxOverlappingLevel = Math.max(maxOverlappingLevel, outsideLink.stackLevel);
+          }
+        }
+      }
+    }
+
+    // Grid group should be one level above the highest overlapping event
+    return maxOverlappingLevel + 1;
+  }
+
+  /**
+   * Render events in a grid container (side-by-side)
+   */
+  private renderGridGroup(group: EventGroup, eventsLayer: HTMLElement, stackLevel: number): void {
+    const groupElement = document.createElement('swp-event-group');
+
+    // Add grid column class based on event count
+    const colCount = group.events.length;
+    groupElement.classList.add(`cols-${colCount}`);
+
+    // Add stack level class for margin-left offset
+    groupElement.classList.add(`stack-level-${stackLevel}`);
+
+    // Position based on earliest event
+    const earliestEvent = group.events[0];
+    const position = this.calculateEventPosition(earliestEvent);
+    groupElement.style.top = `${position.top + 1}px`;
+
+    // Add z-index based on stack level
+    groupElement.style.zIndex = `${this.stackManager.calculateZIndex(stackLevel)}`;
+
+    // Add stack-link attribute for drag-drop (group acts as a stacked item)
+    const stackLink: StackLink = {
+      stackLevel: stackLevel
+      // prev/next will be handled by drag-drop manager if needed
+    };
+    this.stackManager.applyStackLinkToElement(groupElement, stackLink);
+
+    // NO height on the group - it should auto-size based on children
+
+    // Render each event within the grid
+    group.events.forEach(event => {
+      const element = this.renderEventInGrid(event, earliestEvent.start);
+      groupElement.appendChild(element);
+    });
+
+    eventsLayer.appendChild(groupElement);
+  }
+
+  /**
+   * Render event within a grid container (relative positioning)
+   */
+  private renderEventInGrid(event: CalendarEvent, containerStart: Date): HTMLElement {
+    const element = SwpEventElement.fromCalendarEvent(event);
+
+    // Calculate event height
+    const position = this.calculateEventPosition(event);
+
+    // Events in grid are positioned relatively - NO top offset needed
+    // The grid container itself is positioned absolutely with the correct top
+    element.style.position = 'relative';
+    element.style.height = `${position.height - 3}px`;
+
+    return element;
+  }
+
+
   private renderEvent(event: CalendarEvent): HTMLElement {
     const element = SwpEventElement.fromCalendarEvent(event);