version 3.0.6: scrollable views, auto-calculate events, and UX improvements

Major Features:
- Add auto-calculate for maxEventsPerCell (new default: -1)
  - Intelligently calculates how many events fit based on cell height
  - Fully responsive to calendar size and screen dimensions
  - Options: -1 (auto), 0 (unlimited), 1+ (fixed number)
- Implement scrollable views with fixed headers
  - Week/day/list views have max-height: 650px with scrollable content
  - Headers and toolbar stay fixed while scrolling
  - Month view maintains natural expanding height
  - Consistent custom scrollbar styling across all views

Improvements:
- Week/day all-day events now always show titles on continuation segments
- List view sticky date headers have opaque background (no transparency)
- Calendar maintains height during loading (no layout shift)
- Added --cal-bg-secondary CSS variable for consistent backgrounds

Bug Fixes:
- Fixed calendar rebuilding entire shell during event fetching
- Prevented page content jumping when loading events
- Improved loading spinner overlay behavior

Documentation:
- Updated README.md with new maxEventsPerCell options
- Updated docs.html with complete feature documentation
- Updated index.html demo to support -1 value

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: pclslopes

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+No unreleased changes yet.
+
 ## [3.0.6] - 2026-02-24
 
 ### Added
@@ -17,6 +19,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Touch support for drag and drop on mobile/tablet devices
 - Visual feedback during drag operations with 15-minute snap-to-grid in week/day views
 - Cross-boundary conversion (timed ↔ all-day events when dragging between sections)
+- Auto-calculate feature for `maxEventsPerCell`: set to `-1` to automatically calculate how many events fit based on cell height
+
+### Changed
+- **`maxEventsPerCell` default changed from `3` to `-1`** (auto-calculate mode)
+  - `-1` = Auto-calculate based on cell height (responsive, adapts to calendar size)
+  - `0` = Show all events, cells expand infinitely
+  - `1+` = Show exactly that number, rest in "+N more"
+- Week, day, and list views now have a max-height of 650px and scroll content while keeping headers and toolbar fixed in place
+- Month view maintains its natural expanding height based on number of weeks and events per cell
+- All scrollable views use consistent custom scrollbar styling
+- Calendar adapts to container height: if you set a custom height on the container div, week/day/list views will respect it
+- Week/day view all-day events now always display titles on continuation segments (matches day view behavior)
+
+### Fixed
+- List view sticky date headers now have opaque background to prevent events showing through when scrolling
+- Calendar no longer rebuilds entire shell during event fetching, preventing layout shift and page content jumping
 
 ## [3.0.5] - 2026-02-23
 

README.md

@@ -168,7 +168,7 @@ export class CalendarComponent {
 | `showTimeInItems` | boolean | `true` | Show time in event items |
 | `showGridLines` | boolean | `true` | Show calendar grid lines |
 | `showBorder` | boolean | `true` | Show calendar outer border |
-| `maxEventsPerCell` | number | `3` | Maximum events per cell in month view before showing "+N more". Set to `0` for unlimited (show all events) |
+| `maxEventsPerCell` | number | `-1` | Maximum events per cell in month view. `-1` = auto-calculate based on cell height (responsive), `0` = unlimited (show all events), `1+` = show exactly that number |
 | `showToolbar` | boolean | `true` | Show the toolbar |
 | `showTodayButton` | boolean | `true` | Show "Today" button |
 | `showNavigation` | boolean | `true` | Show prev/next navigation arrows |

css/simple-calendar-js.css

@@ -1,5 +1,5 @@
 /**
- * SimpleCalendarJs v3.0.5 — simple-calendar-js.css
+ * SimpleCalendarJs v3.0.6 — simple-calendar-js.css
  * A clean, modern, and feature-rich JavaScript calendar component with zero dependencies
  *
  * @author Pedro Lopes <simplecalendarjs@gmail.com>
@@ -13,6 +13,7 @@
 /* ===== CUSTOM PROPERTIES (Theming Tokens) ===== */
 :root {
   --cal-bg:                  #ffffff;
+  --cal-bg-secondary:        #f9fafb;
   --cal-text:                #111827;
   --cal-text-subtle:         #6b7280;
   --cal-text-muted:          #9ca3af;
@@ -74,11 +75,10 @@
   background: var(--cal-bg);
   border: 1px solid var(--cal-border);
   border-radius: var(--cal-radius);
-  overflow: visible;
+  overflow: hidden;
   display: flex;
   flex-direction: column;
   position: relative;
-  min-height: 500px;
   -webkit-font-smoothing: antialiased;
 }
 
@@ -573,8 +573,8 @@
 .uc-day-view {
   display: flex;
   flex-direction: column;
-  flex: 1;
-  overflow: visible;
+  max-height: 650px;
+  overflow: hidden;
   border-radius: 0 0 var(--cal-radius) var(--cal-radius);
 }
 
@@ -875,10 +875,26 @@
 
 .uc-list-view {
   padding: 0;
-  overflow: visible;
+  max-height: 650px;
+  overflow-y: auto;
+  overflow-x: hidden;
   border-radius: 0 0 var(--cal-radius) var(--cal-radius);
 }
 
+/* Scrollbar styling for list view */
+.uc-list-view::-webkit-scrollbar {
+  width: 6px;
+}
+
+.uc-list-view::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.uc-list-view::-webkit-scrollbar-thumb {
+  background: var(--cal-border-strong);
+  border-radius: 3px;
+}
+
 .uc-list-empty {
   display: flex;
   align-items: center;
@@ -1167,6 +1183,7 @@
 .uc-calendar.uc-dark,
 .uc-dark .uc-calendar {
   --cal-bg:              #1f2937;
+  --cal-bg-secondary:    #111827;
   --cal-text:            #f9fafb;
   --cal-text-subtle:     #9ca3af;
   --cal-text-muted:      #6b7280;

docs.html

@@ -414,8 +414,8 @@ <h3>View Options</h3>
             <tr>
               <td><code>maxEventsPerCell</code></td>
               <td>Number</td>
-              <td><code>3</code></td>
-              <td>Maximum events per cell in month view before showing "+N more". Set to <code>0</code> for unlimited (show all events)</td>
+              <td><code>-1</code></td>
+              <td>Maximum events per cell in month view. <code>-1</code> = auto-calculate based on cell height (responsive), <code>0</code> = unlimited (show all events), <code>1+</code> = show exactly that number</td>
             </tr>
           </tbody>
         </table>

index.html

@@ -712,8 +712,8 @@ <h1>SimpleCalendarJs</h1>
 
       <div class="option-group">
         <span class="option-label">Max Events Per Cell</span>
-        <input type="number" class="option-select" id="opt-max-events" min="0" max="20" value="3" style="width: 80px; padding: 6px 10px;">
-        <span style="font-size: 11px; color: var(--text-muted); margin-left: 8px;">(0 = unlimited)</span>
+        <input type="number" class="option-select" id="opt-max-events" min="-1" max="20" value="-1" style="width: 80px; padding: 6px 10px;">
+        <span style="font-size: 11px; color: var(--text-muted); margin-left: 8px;">(-1 = auto, 0 = unlimited)</span>
       </div>
 
       <div class="option-group">
@@ -1006,7 +1006,7 @@ <h1>SimpleCalendarJs</h1>
       showGridLines: true,
       showBorder: true,
       showTooltips: true,
-      maxEventsPerCell: 3,
+      maxEventsPerCell: -1,
       listDaysForward: 30,
       showToolbar: true,
       showTodayButton: true,
@@ -1238,12 +1238,13 @@ <h1>SimpleCalendarJs</h1>
 
     maxEventsInput.addEventListener('change', () => {
       const value = parseInt(maxEventsInput.value, 10);
-      if (isNaN(value) || value < 0) {
+      if (isNaN(value) || value < -1) {
         maxEventsInput.value = opts.maxEventsPerCell;
         return;
       }
       opts.maxEventsPerCell = value;
-      log('opt', 'tag-opt', `maxEventsPerCell → ${opts.maxEventsPerCell}${value === 0 ? ' (unlimited)' : ''}`);
+      const modeLabel = value === 0 ? ' (unlimited)' : value === -1 ? ' (auto)' : '';
+      log('opt', 'tag-opt', `maxEventsPerCell → ${opts.maxEventsPerCell}${modeLabel}`);
       createCalendar();
     });
 

js/simple-calendar-js.js

@@ -1,5 +1,5 @@
 /**
- * SimpleCalendarJs v3.0.5
+ * SimpleCalendarJs v3.0.6
  * A clean, modern, and feature-rich JavaScript calendar component with zero dependencies
  *
  * @author Pedro Lopes <simplecalendarjs@gmail.com>
@@ -372,7 +372,7 @@
           showViewSwitcher: true,
           showTooltips: true,
           showBorder: true,
-          maxEventsPerCell: 3,
+          maxEventsPerCell: -1,
           listDaysForward: 30,
           enabledViews: ['month', 'week', 'day'],
           enableDragDrop: false,
@@ -443,6 +443,9 @@
         }
       }
 
+      // Build the shell once during initialization
+      this._root.innerHTML = this._buildShell();
+
       this._fetchAndRender();
       this._startNowUpdater();
     }
@@ -555,8 +558,8 @@
     }
 
     async _fetchAndRender() {
-      // Build the shell immediately (updates toolbar title + clears view)
-      this._root.innerHTML = this._buildShell();
+      // Update toolbar only (don't rebuild entire shell)
+      this._updateToolbar();
 
       if (!this._opts.fetchEvents) {
         this._renderView();
@@ -630,6 +633,10 @@
         this._root.classList.add('uc-unlimited-events');
         // Remove cell min-height override for unlimited mode
         this._root.style.removeProperty('--cal-cell-min-height');
+      } else if (this._opts.maxEventsPerCell === -1) {
+        this._root.classList.remove('uc-unlimited-events');
+        // Auto-calculate mode: use default CSS value, don't override
+        this._root.style.removeProperty('--cal-cell-min-height');
       } else {
         this._root.classList.remove('uc-unlimited-events');
         // Set cell min-height based on maxEventsPerCell to match maximum row height
@@ -685,6 +692,18 @@
       `;
     }
 
+    _updateToolbar() {
+      const toolbar = this._root.querySelector('.uc-toolbar');
+      if (toolbar) {
+        const temp = document.createElement('div');
+        temp.innerHTML = this._buildToolbar();
+        const newToolbar = temp.firstElementChild;
+        if (newToolbar) {
+          toolbar.replaceWith(newToolbar);
+        }
+      }
+    }
+
     _buildToolbar() {
       if (!this._opts.showToolbar) return '';
 
@@ -857,7 +876,24 @@
 
     _buildWeekRow(weekDates, allEvents) {
       const curMonth = this._date.getMonth();
-      const MAX = this._opts.maxEventsPerCell === 0 ? Infinity : this._opts.maxEventsPerCell;
+
+      // Calculate MAX based on maxEventsPerCell option
+      let MAX;
+      if (this._opts.maxEventsPerCell === 0) {
+        MAX = Infinity; // Show all events
+      } else if (this._opts.maxEventsPerCell === -1) {
+        // Auto-calculate based on cell height
+        // Get the computed cell min-height (default is 112px from CSS)
+        const computedStyle = getComputedStyle(this._root);
+        const cellMinHeight = parseInt(computedStyle.getPropertyValue('--cal-cell-min-height') || '112');
+        // Formula: (cellHeight - headerHeight - moreLink) / eventHeightWithGap
+        // cellHeight - 30 (header) - 28 (+N more space) / 24 (event + gap)
+        MAX = Math.floor((cellMinHeight - 30 - 28) / 24);
+        // Ensure at least 1 event is shown
+        MAX = Math.max(1, MAX);
+      } else {
+        MAX = this._opts.maxEventsPerCell; // Use specified number
+      }
 
       // Separate multi-day from single-day events
       const multiDay = allEvents.filter(isMultiDay);
@@ -1146,7 +1182,7 @@
                style="left:calc(${left}% + 2px);width:calc(${width}% - 4px);top:${topCss};background:${esc(color)};border-radius:${rl} ${rr} ${rr} ${rl};"
                data-event-id="${esc(event.id)}" data-action="event-click"
                ${tooltipAttr}>
-            ${isStart ? `<span class="uc-event-title">${esc(event.title)}</span>` : '&nbsp;'}
+            <span class="uc-event-title">${esc(event.title)}</span>
             ${resizeHandle}
           </div>`;
       }