Improve calendar navigation UX with loading skeleton and optional sequential months

README.md

@@ -85,6 +85,41 @@ add_filter('se_event_calendar_link_text', function( string $link_text ) {
 }, 10, 1);
 ```
 
+### Calendar Rendering
+
+#### Filter day events before calendar markup is built
+```php
+add_filter( 'simple_events_calendar_day_events', function( array $day_events, DateTime $date, int $start_timestamp, int $end_timestamp ) {
+	$unique_events = array();
+	$seen_keys     = array();
+
+	foreach ( $day_events as $event ) {
+		if ( ! is_object( $event ) || ! isset( $event->ID, $event->event_start_date, $event->event_end_date ) ) {
+			$unique_events[] = $event;
+			continue;
+		}
+
+		$key = implode(
+			'|',
+			array(
+				(string) $event->ID,
+				$event->event_start_date instanceof DateTime ? $event->event_start_date->format( 'U' ) : '',
+				$event->event_end_date instanceof DateTime ? $event->event_end_date->format( 'U' ) : '',
+			)
+		);
+
+		if ( isset( $seen_keys[ $key ] ) ) {
+			continue;
+		}
+
+		$seen_keys[ $key ] = true;
+		$unique_events[]   = $event;
+	}
+
+	return $unique_events;
+}, 10, 4 );
+```
+
 ### Cron Tasks for Event Start Date
 
 > When the cron task runs to update the event start date to a future date if its passed and future dates exist.
@@ -189,6 +224,12 @@ Copy the `team51-focal-point` folder to your `mu-plugins` directory.
 
 ## Changelog
 
+### 2.1.2
+
+- **Calendar loading UX:** added a loading skeleton while calendar month requests are in flight.
+- **Calendar mobile interaction:** fixed day selection logic on mobile breakpoints when themes customize hidden/mobile display rules.
+- **Calendar navigation:** added a "Show Months in Order" option for sequential month navigation (defaults to off for existing blocks).
+
 ### 2.1.1
 
 - **Loop Event Info block:** added a configurable HTML wrapper element (`div`/`p`/`h1`–`h6`), per-block date and time format overrides, and a query offset control.

package.json

@@ -1,6 +1,6 @@
 {
     "name": "wpcomsp-simple-events",
-    "version": "2.1.1",
+    "version": "2.1.2",
     "description": "A simple Gutenberg-first event management plugin that integrates with WooCommerce Box Office.",
     "author": {
         "name": "WordPress.com Special Projects Team",

plugin.php

@@ -3,7 +3,7 @@
  * Simple Events Plugin bootstrap file.
  *
  * @since       1.0.0
- * @version     2.1.1
+ * @version     2.1.2
  * @author      WordPress.com Special Projects
  * @license     GPL-3.0-or-later
  *
@@ -14,7 +14,7 @@
  * Description:             Event management frontend for WooCommerce Box Office.
  * Requires at least:       6.5
  * Tested up to:            6.9
- * Version:                 2.1.1
+ * Version:                 2.1.2
  * Requires PHP:            8.0
  * Author:                  WordPress.com Special Projects
  * Author URI:              https://wpspecialprojects.wordpress.com
@@ -32,7 +32,7 @@
 function_exists( 'get_plugin_data' ) || require_once ABSPATH . 'wp-admin/includes/plugin.php';
 define( 'SE_METADATA', get_plugin_data( __FILE__, false, false ) );
 
-define( 'SE_VERSION', '2.1.1' );
+define( 'SE_VERSION', '2.1.2' );
 define( 'SE_BASENAME', plugin_basename( __FILE__ ) );
 define( 'SE_PLUGIN_DIR', untrailingslashit( plugin_dir_path( __FILE__ ) ) );
 define( 'SE_PLUGIN_URL', untrailingslashit( plugin_dir_url( __FILE__ ) ) );

src/blocks/calendar/block.json

@@ -39,6 +39,10 @@
 			"type": "boolean",
 			"default": false
 		},
+		"sequentialMonths": {
+			"type": "boolean",
+			"default": false
+		},
 		"hideNeighbourEvents": {
 			"type": "boolean",
 			"default": false

src/blocks/calendar/calendar.js

@@ -45,18 +45,14 @@ export default class Calendar {
 	/**
 	 * Check if mobile view
 	 *
-	 * @param  calendarItem
 	 * @return {boolean}
 	 */
-	isMobile( calendarItem ) {
-		const mobileElements = calendarItem.querySelectorAll( this.DOM.desktopElements );
-		if ( mobileElements.length ) {
-			if ( 'none' === window.getComputedStyle( mobileElements[ 0 ], null ).display ) {
-				return true;
-			}
+	isMobile() {
+		if ( window.matchMedia ) {
+			return window.matchMedia( '(max-width: 767px)' ).matches;
 		}
 
-		return false;
+		return window.innerWidth <= 767;
 	}
 
 	/**
@@ -70,7 +66,7 @@ export default class Calendar {
 		if ( calendarDays.length ) {
 			calendarDays.forEach( ( item ) => {
 				item.addEventListener( 'click', ( event ) => {
-					if ( ! this.isMobile( calendarItem ) ) {
+					if ( ! this.isMobile() ) {
 						return;
 					}
 
@@ -134,13 +130,80 @@ export default class Calendar {
 		}
 	}
 
+	/**
+	 * Show loading skeleton and hide current calendar content.
+	 *
+	 * @param {Element} calendarItem Calendar container element.
+	 */
+	showLoading( calendarItem ) {
+		const skeleton = calendarItem.querySelector(
+			'[data-js="simple-events-calendar-skeleton"]'
+		);
+		const content = calendarItem.querySelector(
+			'[data-js="simple-events-calendar-content"]'
+		);
+
+		if ( skeleton ) {
+			skeleton.classList.remove(
+				'simple-events-calendar-skeleton--hidden'
+			);
+		}
+
+		if ( content ) {
+			content.classList.add( 'simple-events-calendar-content--hidden' );
+		}
+	}
+
+	/**
+	 * Update the visible calendar markup after request completes.
+	 *
+	 * @param {Element} calendarItem Calendar container element.
+	 * @param {string}  html         Updated calendar main HTML.
+	 */
+	updateContent( calendarItem, html ) {
+		const content = calendarItem.querySelector(
+			'[data-js="simple-events-calendar-content"]'
+		);
+
+		if ( content ) {
+			content.innerHTML = html;
+			return;
+		}
+
+		calendarItem.innerHTML = html;
+	}
+
+	/**
+	 * Hide loading skeleton and re-show calendar content.
+	 *
+	 * @param {Element} calendarItem Calendar container element.
+	 */
+	hideLoading( calendarItem ) {
+		const skeleton = calendarItem.querySelector(
+			'[data-js="simple-events-calendar-skeleton"]'
+		);
+		const content = calendarItem.querySelector(
+			'[data-js="simple-events-calendar-content"]'
+		);
+
+		if ( skeleton ) {
+			skeleton.classList.add( 'simple-events-calendar-skeleton--hidden' );
+		}
+
+		if ( content ) {
+			content.classList.remove( 'simple-events-calendar-content--hidden' );
+		}
+	}
+
 	/**
 	 * Send calendar API request
 	 *
 	 * @param date
 	 * @param calendarItem
 	 */
 	sendCalendarRequest( date, calendarItem ) {
+		this.showLoading( calendarItem );
+
 		/**
 		 * Convert GET request to POST
 		 * Implemented to send block attributes in body instead of URL.
@@ -154,12 +217,18 @@ export default class Calendar {
 			},
 		} ).then( ( result ) => {
 			if ( result.html ) {
-				calendarItem.innerHTML = result.html;
-				this.initListeners( calendarItem );
+				this.updateContent( calendarItem, result.html );
 			} else {
 				console.log( result );
 			}
-		});
+		} )
+			.catch( () => {
+				// Keep the existing calendar content if request fails.
+			} )
+			.finally( () => {
+				this.hideLoading( calendarItem );
+				this.initListeners( calendarItem );
+			} );
 	}
 
 	/**

src/blocks/calendar/index.js

@@ -39,6 +39,20 @@ registerBlockType( 'simple-events/calendar', {
 				</BlockControls>
 				<InspectorControls>
 					<PanelBody title="Event Configuration" initialOpen={ true }>
+						<ToggleControl
+							label={ __(
+								'Show Months in Order',
+								'simple-events'
+							) }
+							help={ __(
+								'When enabled, months move one at a time and the calendar opens on the first month that has events (from today if the current month is empty). When disabled, navigation jumps only between months that have events.',
+								'simple-events'
+							) }
+							checked={ attributes?.sequentialMonths === true }
+							onChange={ ( value ) =>
+								setAttributes( { sequentialMonths: value } )
+							}
+						/>
 						<ToggleControl  
 							label={ __(
 								'Hide Events on Neighbouring Months',

src/blocks/calendar/style.scss

@@ -5,6 +5,92 @@
  */
 
 @import '../common.scss';
+
+.simple-events-calendar-skeleton {
+	&--hidden {
+		display: none;
+	}
+
+	&:not(.simple-events-calendar-skeleton--hidden) {
+		.simple-events-calendar-skeleton__top-bar > span,
+		.simple-events-calendar-skeleton__header > span,
+		.simple-events-calendar-skeleton__day {
+			background: linear-gradient(90deg, #454545 25%, #515151 50%, #454545 75%);
+			background-size: 200% 100%;
+			animation: simple-events-skeleton-shimmer 2.5s ease-in-out infinite;
+			border-radius: 4px;
+		}
+	}
+
+	.simple-events-calendar-skeleton__top-bar {
+		display: flex;
+		flex-direction: row;
+		gap: 20px;
+		align-items: center;
+		margin-bottom: 20px;
+		justify-content: space-between;
+
+		> span {
+			&:first-child {
+				width: 50px;
+				height: 28px;
+			}
+			&:nth-child(2) {
+				flex: 1;
+				max-width: 200px;
+				height: 28px;
+			}
+			&:nth-child(3) {
+				width: 80px;
+				height: 28px;
+			}
+		}
+	}
+
+	.simple-events-calendar-skeleton__header {
+		display: flex;
+		gap: 4px;
+		margin-bottom: 12px;
+
+		> span {
+			flex: 1;
+			height: 20px;
+		}
+	}
+
+	.simple-events-calendar-skeleton__body {
+		min-height: 500px;
+	}
+
+	.simple-events-calendar-skeleton__week {
+		display: flex;
+		gap: 4px;
+		margin-bottom: 4px;
+	}
+
+	.simple-events-calendar-skeleton__day {
+		flex: 1;
+		min-height: 100px;
+
+		@include max-mobile {
+			min-height: 50px;
+		}
+	}
+}
+
+@keyframes simple-events-skeleton-shimmer {
+	0% {
+		background-position: 200% 0;
+	}
+	100% {
+		background-position: -200% 0;
+	}
+}
+
+.simple-events-calendar-content--hidden {
+	display: none;
+}
+
 .simple-events-calendar {
     margin-left: auto;
     margin-right: auto;
@@ -272,4 +358,4 @@
             font-size: 14px;
         }
     }
-}
+}