Upcoming events archive with month grid

<?php
/**
 * Event archive query + month grid.
 *
 * Assumes a post type "acme_event" with a "Y-m-d" meta key "acme_event_date".
 *
 * @package Acme_Theme
 */

defined( 'ABSPATH' ) || exit;

// 1. Archive: upcoming first, optional ?month=YYYY-MM filter.
function acme_events_query( WP_Query $query ): void {
	if ( is_admin() || ! $query->is_main_query() || ! $query->is_post_type_archive( 'acme_event' ) ) {
		return;
	}

	$month = isset( $_GET['month'] ) ? sanitize_text_field( wp_unslash( $_GET['month'] ) ) : '';
	if ( preg_match( '/^\d{4}-(0[1-9]|1[0-2])$/', $month ) ) {
		$compare = array( 'key' => 'acme_event_date', 'value' => array( "$month-01", "$month-31" ), 'compare' => 'BETWEEN', 'type' => 'DATE' );
	} else {
		$compare = array( 'key' => 'acme_event_date', 'value' => wp_date( 'Y-m-d' ), 'compare' => '>=', 'type' => 'DATE' );
	}

	$query->set( 'meta_query', array( $compare ) );
	$query->set( 'meta_key', 'acme_event_date' );
	$query->set( 'orderby', 'meta_value' );
	$query->set( 'order', 'ASC' );
	$query->set( 'posts_per_page', 50 );
}
add_action( 'pre_get_posts', 'acme_events_query' );

// 2. Month grid: returns HTML for a Monday-first calendar.
function acme_events_month_grid( string $month ): string {
	$first = DateTimeImmutable::createFromFormat( '!Y-m', $month ) ?: new DateTimeImmutable( 'first day of this month' );
	$days  = (int) $first->format( 't' );
	$pad   = (int) $first->format( 'N' ) - 1;

	$by_day = array();
	$events = get_posts(
		array(
			'post_type'      => 'acme_event',
			'posts_per_page' => 100,
			'meta_key'       => 'acme_event_date',
			'meta_query'     => array( array( 'key' => 'acme_event_date', 'value' => array( $first->format( 'Y-m-01' ), $first->format( 'Y-m-t' ) ), 'compare' => 'BETWEEN', 'type' => 'DATE' ) ),
		)
	);
	foreach ( $events as $event ) {
		$day = (int) substr( (string) get_post_meta( $event->ID, 'acme_event_date', true ), 8, 2 );
		$by_day[ $day ][] = $event;
	}

	$html = '<table class="acme-cal"><caption>' . esc_html( wp_date( 'F Y', $first->getTimestamp() ) ) . '</caption><tr>';
	foreach ( array( 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun' ) as $label ) {
		$html .= '<th scope="col">' . esc_html( $label ) . '</th>';
	}
	$html .= '</tr><tr>' . str_repeat( '<td></td>', $pad );

	for ( $d = 1; $d <= $days; $d++ ) {
		if ( 0 === ( $pad + $d - 1 ) % 7 && $d > 1 ) {
			$html .= '</tr><tr>';
		}
		$html .= '<td><span class="acme-cal__n">' . $d . '</span>';
		foreach ( $by_day[ $d ] ?? array() as $event ) {
			$html .= '<a href="' . esc_url( get_permalink( $event ) ) . '">' . esc_html( get_the_title( $event ) ) . '</a>';
		}
		$html .= '</td>';
	}
	return $html . '</tr></table>';
}