Add group-class scheduling, instructor assignment, and details/invite management

Group classes now carry a specific class time (alongside date and duration)
and an assigned instructor:

- Schema: add `class_time` (TIME) to `us_offerings`; `Offering` gains
  `normalizeTime`/`sessionWindows`. (Rides the pending 1.0.0->1.1.0 dbDelta
  upgrade, so no version bump.)
- Offering form: class-time field, plus a studio-admin instructor picker
  (plain instructors always own their own classes).
- `ClassSlotReconciler`: assigning an instructor clears their open booking
  slots overlapping each session and flags already-booked lessons that clash
  (a booked lesson is never deleted). Uses new
  `AvailabilityRepository::findOverlapping`.
- Front end: `GET /offerings` exposes `instructor_name`; the enrolment page
  shows who teaches each class and when it meets.

Back-office group-class views redesigned:

- Instructor **My Group Classes** and studio-admin **Group Classes** are now
  per-class summaries with enrolment counts, not flat student lists.
- Each links through (`?class_id=<id>`) to a per-class **details page**
  (schedule panel, roster with payment status, and — for invite-only classes
  — the add/make-available/invite-by-email controls). Invite-only membership
  is managed entirely from this page.
- Invite actions are allowed for the class's owning instructor or any
  `view_all_lessons` studio admin, so an owner-operator (studio admin who also
  teaches) can reach every class's roster and invites from the Group Classes
  page.

Tests: composer test (508), composer lint, composer cs all pass.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

src/Offering/ClassSlotReconciler.php

@@ -0,0 +1,57 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Offering;
+
+use Unsupervised\Schedular\Availability\AvailabilityRepository;
+
+/**
+ * Keeps an instructor's open availability out of the way of the group classes
+ * they teach. When a group class is scheduled (an assigned instructor plus a
+ * date, time, and duration), each session occupies the instructor: any open
+ * private-booking slot that overlaps a session is removed so students cannot
+ * book the instructor at the class time, and any already-booked slot that
+ * overlaps is reported as a conflict for the studio to resolve by hand — a
+ * booked lesson is never silently deleted.
+ */
+class ClassSlotReconciler {
+
+	public function __construct( private AvailabilityRepository $availability ) {}
+
+	/**
+	 * Reconcile the assigned instructor's availability with the class schedule.
+	 *
+	 * @return array{removed: int, conflicts: list<string>} The number of open
+	 *         slots cleared, and the start datetime (`Y-m-d H:i:s`) of each booked
+	 *         slot that still clashes with a session.
+	 */
+	public function reconcile( Offering $offering ): array {
+		if ( Offering::KIND_GROUP_CLASS !== $offering->kind || $offering->instructorId <= 0 ) {
+			return [
+				'removed'   => 0,
+				'conflicts' => [],
+			];
+		}
+
+		$removed   = 0;
+		$conflicts = [];
+
+		foreach ( $offering->sessionWindows() as $window ) {
+			foreach ( $this->availability->findOverlapping( $offering->instructorId, $window['start'], $window['end'] ) as $slot ) {
+				if ( $slot->isBooked ) {
+					$conflicts[] = $slot->startDt;
+					continue;
+				}
+
+				if ( null !== $slot->id && $this->availability->delete( $slot->id ) ) {
+					++$removed;
+				}
+			}
+		}
+
+		return [
+			'removed'   => $removed,
+			'conflicts' => $conflicts,
+		];
+	}
+}

src/Offering/Offering.php

@@ -53,6 +53,7 @@ class Offering {
 		public readonly ?int $capacity = null,
 		public readonly ?string $termStart = null,
 		public readonly ?string $termEnd = null,
+		public readonly ?string $classTime = null,
 		public readonly ?string $scheduleNote = null,
 		public readonly ?string $etransferEmail = null,
 		public readonly ?int $cancellationCutoffHours = null,
@@ -90,6 +91,69 @@ class Offering {
 		return ( new \DateTimeImmutable( $termStart ) )->modify( '+' . ( 7 * $weeks ) . ' days' )->format( 'Y-m-d' );
 	}
 
+	/**
+	 * Normalise a submitted time-of-day to canonical `H:i:s`, or null when it is
+	 * not a real time. Accepts the HTML `time` form (`H:i`, optionally with
+	 * seconds); anything else is rejected so garbage never reaches the TIME column.
+	 */
+	public static function normalizeTime( string $value ): ?string {
+		foreach ( [ 'H:i:s', 'H:i' ] as $format ) {
+			$time = \DateTimeImmutable::createFromFormat( '!' . $format, $value );
+			if ( false !== $time && $time->format( $format ) === $value ) {
+				return $time->format( 'H:i:s' );
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * The concrete start/end datetimes of every session of this group class,
+	 * derived from the class date(s), the class time, and the duration. A weekly
+	 * class yields one window per week from `term_start` through `term_end`; a
+	 * one-off class yields a single window. Returns an empty list unless the
+	 * schedule is fully specified (date, time, and a positive duration), so it can
+	 * never fabricate a session window from partial data.
+	 *
+	 * @return list<array{start: string, end: string}>
+	 */
+	public function sessionWindows(): array {
+		if (
+			null === $this->termStart
+			|| null === $this->classTime
+			|| null === $this->durationMinutes
+			|| $this->durationMinutes <= 0
+		) {
+			return [];
+		}
+
+		$first = \DateTimeImmutable::createFromFormat( '!Y-m-d H:i:s', $this->termStart . ' ' . $this->classTime );
+		if ( false === $first ) {
+			return [];
+		}
+
+		$lastDay = null !== $this->termEnd ? $this->termEnd : $this->termStart;
+		$step    = new \DateInterval( 'PT' . $this->durationMinutes . 'M' );
+
+		$windows   = [];
+		$cursor    = $first;
+		$cursorDay = $cursor->format( 'Y-m-d' );
+
+		// Cap the walk at ten years of weeks so a term_end before term_start (or a
+		// bad value) can never spin into an unbounded loop.
+		for ( $i = 0; $i < 520 && $cursorDay <= $lastDay; $i++ ) {
+			$windows[] = [
+				'start' => $cursor->format( 'Y-m-d H:i:s' ),
+				'end'   => $cursor->add( $step )->format( 'Y-m-d H:i:s' ),
+			];
+
+			$cursor    = $cursor->modify( '+7 days' );
+			$cursorDay = $cursor->format( 'Y-m-d' );
+		}
+
+		return $windows;
+	}
+
 	public static function fromRow( \stdClass $row ): self {
 		return new self(
 			instructorId:    Val::int( $row->instructor_id ),
@@ -104,6 +168,7 @@ class Offering {
 			capacity:        Val::intOrNull( $row->capacity ),
 			termStart:       Val::stringOrNull( $row->term_start ),
 			termEnd:         Val::stringOrNull( $row->term_end ),
+			classTime:       Val::stringOrNull( $row->class_time ?? null ),
 			scheduleNote:    Val::stringOrNull( $row->schedule_note ),
 			etransferEmail:  Val::stringOrNull( $row->etransfer_email ),
 			cancellationCutoffHours: Val::intOrNull( $row->cancellation_cutoff_hours ),
@@ -137,6 +202,7 @@ class Offering {
 			'capacity'                  => $this->capacity,
 			'term_start'                => $this->termStart,
 			'term_end'                  => $this->termEnd,
+			'class_time'                => $this->classTime,
 			'schedule_note'             => $this->scheduleNote,
 			'cancellation_cutoff_hours' => $this->cancellationCutoffHours,
 			'access_mode'               => $this->accessMode,

src/Offering/OfferingController.php

@@ -8,7 +8,10 @@ use Unsupervised\Schedular\Val;
 
 class OfferingController {
 
-	public function __construct( private OfferingRepository $repository ) {}
+	public function __construct(
+		private OfferingRepository $repository,
+		private ClassSlotReconciler $reconciler,
+	) {}
 
 	public function renderPage(): void {
 		if ( ! current_user_can( RoleManager::CAP_MANAGE_OFFERINGS ) ) {
@@ -18,10 +21,15 @@ class OfferingController {
 		$instructorId = get_current_user_id();
 		$manageAll    = current_user_can( RoleManager::CAP_MANAGE_INSTRUCTORS );
 
+		$notice = '';
 		if ( isset( $_POST['usc_action'] ) && check_admin_referer( 'usc_offering_action' ) ) {
-			$this->handleFormAction( $instructorId, $manageAll );
+			$notice = $this->handleFormAction( $instructorId, $manageAll );
 		}
 
+		// Studio admins may assign any instructor to a class; a plain instructor
+		// only ever creates classes for themselves, so the picker is theirs alone.
+		$instructors = $manageAll ? $this->instructorOptions() : [];
+
 		// View-state query param only (which offering the form is editing) —
 		// nothing is mutated from it, so no nonce applies.
 		// phpcs:disable WordPress.Security.NonceVerification.Recommended
@@ -43,15 +51,22 @@ class OfferingController {
 		include USC_PLUGIN_DIR . 'templates/admin/offerings.php';
 	}
 
-	private function handleFormAction( int $instructorId, bool $manageAll ): void {
+	/**
+	 * Process the posted add/update/delete action, returning a status notice for
+	 * display (e.g. how many booking slots a scheduled class cleared, or that a
+	 * booked lesson clashes with it). An empty string means nothing to report.
+	 */
+	private function handleFormAction( int $instructorId, bool $manageAll ): string {
 		// Nonce is verified by the caller (renderPage) before this method runs.
 		// phpcs:disable WordPress.Security.NonceVerification.Missing
 		$action = sanitize_key( Val::string( wp_unslash( $_POST['usc_action'] ?? '' ) ) );
 
 		if ( 'add' === $action ) {
-			$offering = $this->offeringFromPost( $instructorId );
+			$offering = $this->offeringFromPost( $instructorId, $manageAll );
 			if ( null !== $offering ) {
 				$this->repository->insert( $offering );
+
+				return $this->reconcileNotice( $offering );
 			}
 		}
 
@@ -60,9 +75,11 @@ class OfferingController {
 			if ( $offeringId > 0 ) {
 				$existing = $this->repository->findById( $offeringId );
 				if ( $existing && ( $manageAll || $existing->instructorId === $instructorId ) ) {
-					$offering = $this->offeringFromPost( $instructorId, $existing );
+					$offering = $this->offeringFromPost( $instructorId, $manageAll, $existing );
 					if ( null !== $offering ) {
 						$this->repository->update( $offeringId, $offering );
+
+						return $this->reconcileNotice( $offering );
 					}
 				}
 			}
@@ -78,15 +95,86 @@ class OfferingController {
 			}
 		}
 		// phpcs:enable WordPress.Security.NonceVerification.Missing
+
+		return '';
+	}
+
+	/**
+	 * Clear the assigned instructor's open booking slots that collide with a
+	 * scheduled group class and describe the result, warning about any booked
+	 * lesson that clashes (which the studio must resolve by hand).
+	 */
+	private function reconcileNotice( Offering $offering ): string {
+		if ( Offering::KIND_GROUP_CLASS !== $offering->kind ) {
+			return '';
+		}
+
+		$result = $this->reconciler->reconcile( $offering );
+		$parts  = [];
+
+		if ( $result['removed'] > 0 ) {
+			$parts[] = sprintf(
+				/* translators: %d: number of open booking slots removed. */
+				_n(
+					'%d open booking slot was removed to hold the class time.',
+					'%d open booking slots were removed to hold the class time.',
+					$result['removed'],
+					'unsupervised-schedular'
+				),
+				$result['removed']
+			);
+		}
+
+		foreach ( $result['conflicts'] as $startDt ) {
+			$parts[] = sprintf(
+				/* translators: %s: date and time of the already-booked lesson that clashes. */
+				esc_html__( 'Conflict: a lesson is already booked at %s during this class.', 'unsupervised-schedular' ),
+				(string) mysql2date( 'M j, Y g:i a', $startDt )
+			);
+		}
+
+		return implode( ' ', $parts );
+	}
+
+	/**
+	 * Registered instructors offered in the assignment select, by display name.
+	 *
+	 * @return list<array{id: int, name: string}>
+	 */
+	private function instructorOptions(): array {
+		$users = array_filter(
+			get_users(
+				[
+					'role'    => RoleManager::INSTRUCTOR,
+					'orderby' => 'display_name',
+					'order'   => 'ASC',
+				]
+			),
+			static fn( mixed $u ): bool => $u instanceof \WP_User
+		);
+
+		return array_values(
+			array_map(
+				static fn( \WP_User $u ): array => [
+					'id'   => (int) $u->ID,
+					'name' => '' !== (string) $u->display_name ? (string) $u->display_name : (string) $u->user_email,
+				],
+				$users
+			)
+		);
 	}
 
 	/**
 	 * Build an offering from the submitted add/edit form, or null when the
 	 * submission is invalid. When `$existing` is given the result is an edit:
-	 * it keeps the existing id, owner, and currency so an update can never
-	 * reassign an offering to whoever happens to submit the form.
+	 * it keeps the existing id and currency so an update can never rewrite those
+	 * from whoever submits the form.
+	 *
+	 * The owning instructor normally stays fixed (the creator on add, the existing
+	 * owner on edit). A studio admin (`$manageAll`) may instead assign the class to
+	 * any instructor via the picker; a blank or absent choice keeps the default.
 	 */
-	private function offeringFromPost( int $instructorId, ?Offering $existing = null ): ?Offering {
+	private function offeringFromPost( int $instructorId, bool $manageAll, ?Offering $existing = null ): ?Offering {
 		// Nonce is verified by the caller (renderPage) before this method runs.
 		// phpcs:disable WordPress.Security.NonceVerification.Missing
 		$title = sanitize_text_field( Val::string( wp_unslash( $_POST['title'] ?? '' ) ) );
@@ -119,8 +207,10 @@ class OfferingController {
 			$termEnd    = 'weekly' === $recurrence ? Offering::weeklyTermEnd( $termStart, $sessions ) : $termStart;
 		}
 
+		$classTime = Offering::normalizeTime( sanitize_text_field( Val::string( wp_unslash( $_POST['class_time'] ?? '' ) ) ) );
+
 		return new Offering(
-			instructorId:    null !== $existing ? $existing->instructorId : $instructorId,
+			instructorId:    $this->resolveInstructorId( $instructorId, $manageAll, $existing ),
 			kind:            $kind,
 			title:           $title,
 			price:           max( 0.0, (float) sanitize_text_field( Val::string( wp_unslash( $_POST['price'] ?? '0' ) ) ) ),
@@ -132,6 +222,7 @@ class OfferingController {
 			capacity:        $capacity > 0 ? $capacity : null,
 			termStart:       $termStart,
 			termEnd:         $termEnd,
+			classTime:       $classTime,
 			scheduleNote:    $this->nullableText( sanitize_text_field( Val::string( wp_unslash( $_POST['schedule_note'] ?? '' ) ) ) ),
 			etransferEmail:  $this->nullableText( sanitize_email( Val::string( wp_unslash( $_POST['etransfer_email'] ?? '' ) ) ) ),
 			cancellationCutoffHours: $cutoffHours,
@@ -142,6 +233,26 @@ class OfferingController {
 		// phpcs:enable WordPress.Security.NonceVerification.Missing
 	}
 
+	/**
+	 * The instructor the offering should belong to. A studio admin may reassign it
+	 * via the posted `class_instructor_id`; otherwise it stays with the existing
+	 * owner (edit) or the current user (add). A plain instructor can never change
+	 * the owner, so the posted value is ignored unless `$manageAll` is set.
+	 */
+	private function resolveInstructorId( int $instructorId, bool $manageAll, ?Offering $existing ): int {
+		$fallback = null !== $existing ? $existing->instructorId : $instructorId;
+
+		if ( ! $manageAll ) {
+			return $fallback;
+		}
+
+		// Nonce is verified by the caller (renderPage) before this method runs.
+		// phpcs:ignore WordPress.Security.NonceVerification.Missing
+		$posted = absint( Val::int( $_POST['class_instructor_id'] ?? 0 ) );
+
+		return $posted > 0 ? $posted : $fallback;
+	}
+
 	private function nullableText( string $value ): ?string {
 		return '' === $value ? null : $value;
 	}

src/Offering/OfferingEndpoint.php

@@ -77,8 +77,25 @@ class OfferingEndpoint {
 			$offerings[] = $granted;
 		}
 
-		// Public listing: omit the private e-transfer destination email.
-		return new \WP_REST_Response( array_map( fn( Offering $o ) => $o->toArray( includeEtransferEmail: false ), $offerings ), 200 );
+		// Public listing: omit the private e-transfer destination email, and
+		// attach the assigned instructor's display name so the front end can show
+		// students who teaches each class.
+		return new \WP_REST_Response( array_map( [ $this, 'present' ], $offerings ), 200 );
+	}
+
+	/**
+	 * A public-facing offering array with the assigned instructor's display name
+	 * added (empty when the instructor account no longer exists).
+	 *
+	 * @return array<string, mixed>
+	 */
+	private function present( Offering $offering ): array {
+		$out  = $offering->toArray( includeEtransferEmail: false );
+		$user = get_userdata( $offering->instructorId );
+
+		$out['instructor_name'] = $user instanceof \WP_User ? $user->display_name : '';
+
+		return $out;
 	}
 
 	/**

src/Offering/OfferingRepository.php

@@ -14,12 +14,12 @@ class OfferingRepository {
 	/**
 	 * Column formats aligned to {@see columns()} (instructor_id, kind, title,
 	 * description, duration_minutes, price, currency, billing_mode, allow_weekly,
-	 * capacity, term_start, term_end, schedule_note, etransfer_email,
+	 * capacity, term_start, term_end, class_time, schedule_note, etransfer_email,
 	 * cancellation_cutoff_hours, access_mode, is_active).
 	 *
 	 * @var list<string>
 	 */
-	private const COLUMN_FORMATS = [ '%d', '%s', '%s', '%s', '%d', '%f', '%s', '%s', '%d', '%d', '%s', '%s', '%s', '%s', '%d', '%s', '%d' ];
+	private const COLUMN_FORMATS = [ '%d', '%s', '%s', '%s', '%d', '%f', '%s', '%s', '%d', '%d', '%s', '%s', '%s', '%s', '%s', '%d', '%s', '%d' ];
 
 	public function insert( Offering $offering ): int {
 		$this->db->insert(
@@ -60,6 +60,7 @@ class OfferingRepository {
 			'capacity'                  => $offering->capacity,
 			'term_start'                => $offering->termStart,
 			'term_end'                  => $offering->termEnd,
+			'class_time'                => $offering->classTime,
 			'schedule_note'             => $offering->scheduleNote,
 			'etransfer_email'           => $offering->etransferEmail,
 			'cancellation_cutoff_hours' => $offering->cancellationCutoffHours,