fix: Enhance SideEventArranger with configurable layout styles for overlapping events.

Author: kavantrivedi

lib/src/event_arrangers/side_event_arranger.dart

@@ -4,26 +4,36 @@
 
 part of 'event_arrangers.dart';
 
-/// Arranges overlapping calendar events side by side, ensuring no visual overlap and optimal use of space.
-/// Supports multi-day and full-day events, fixed or dynamic width allocation, and configurable edge overlap handling.
+/// Arranges overlapping calendar events side by side with configurable layout styles.
 ///
-/// Events are grouped into columns to prevent overlaps, and each event is positioned and sized for best readability.
-/// Use [maxWidth] to constrain event width, and [includeEdges] to control whether touching events are treated as overlapping.
+/// Supports two layout modes:
+/// - **Expanded layout** (default): Events expand to fill available width for maximum readability
+/// - **Cross-event layout**: Overlapping events are positioned side-by-side with reduced width to prevent visual overlap
+///
+/// Also supports multi-day and full-day events, fixed or dynamic width allocation via [maxWidth].
+/// Use [useCrossEventLayout] to switch between expanded and cross-event layouts.
 class SideEventArranger<T extends Object?> extends EventArranger<T> {
   /// This class will provide method that will arrange
   /// all the events side by side.
   const SideEventArranger({
     this.maxWidth,
-    this.includeEdges = false,
+    this.useCrossEventLayout = false,
   });
 
-  /// Decides whether events that are overlapping on edge
-  /// (ex, event1 has the same end-time as the start-time of event 2)
-  /// should be offset or not.
+  /// Controls the layout style for overlapping events.
+  ///
+  /// When `false` (default): Events use expanded layout where each event takes
+  /// full available width, creating a more spacious appearance. Events that only
+  /// touch at edges (e.g., event1 ends at 2:00 PM, event2 starts at 2:00 PM)
+  /// are not treated as overlapping.
   ///
-  /// If includeEdges is true, it will offset the events else it will not.
-  /// Defaults to false.
-  final bool includeEdges;
+  /// When `true`: Events use cross-event layout where overlapping events are
+  /// positioned side-by-side with reduced width (typically half-width), preventing
+  /// any visual overlap. Events that touch at edges are treated as overlapping
+  /// and will be positioned accordingly.
+  ///
+  /// Defaults to false (expanded layout).
+  final bool useCrossEventLayout;
 
   /// If enough space is available, the event slot will
   /// use the specified max width.
@@ -226,15 +236,22 @@ class SideEventArranger<T extends Object?> extends EventArranger<T> {
     return !_eventsOverlap(event, lastEvent);
   }
 
-  /// Returns true if two events overlap in time, considering [includeEdges].
+  /// Returns true if two events overlap in time, considering [useCrossEventLayout].
+  ///
+  /// When [useCrossEventLayout] is `false` (expanded layout):
+  /// - Events that only touch at edges are NOT considered overlapping
+  /// - Example: Event A (1:00-2:00) and Event B (2:00-3:00) do NOT overlap
+  /// - This allows events to expand and use full available width
   ///
-  /// If [includeEdges] is false, events that only touch at edges are not considered overlapping.
-  /// If true, touching events are treated as overlapping.
+  /// When [useCrossEventLayout] is `true` (cross-event layout):
+  /// - Events that touch at edges ARE considered overlapping
+  /// - Example: Event A (1:00-2:00) and Event B (2:00-3:00) DO overlap
+  /// - This ensures side-by-side positioning with reduced (half) width
   ///
   /// Handles edge cases like zero-duration events and identical start/end times.
   /// Optimized for fast arithmetic comparison.
   bool _eventsOverlap(_NormalizedEvent<T> event1, _NormalizedEvent<T> event2) {
-    if (includeEdges) {
+    if (useCrossEventLayout) {
       // Events overlap if they have any overlapping time (including touching edges)
       return event1.effectiveStartTime <= event2.effectiveEndTime &&
           event2.effectiveStartTime <= event1.effectiveEndTime;