Merge remote-tracking branch 'origin/main' into feature/hst-and-reporting

# Conflicts:
#	src/AdminMenu.php

src/AdminMenu.php

@@ -62,6 +62,8 @@ class AdminMenu {
 	}
 
 	public function addPages(): void {
+		$this->addStudioSeparators();
+
 		// Studio-wide dashboard: all upcoming lessons across instructors.
 		add_menu_page(
 			__( 'Scheduler', 'unsupervised-schedular' ),
@@ -70,7 +72,7 @@ class AdminMenu {
 			'us-scheduler',
 			[ $this->lessonController, 'renderAdminDashboard' ],
 			'dashicons-calendar-alt',
-			30
+			40
 		);
 
 		// Instructor: manage their own availability.
@@ -81,7 +83,7 @@ class AdminMenu {
 			'us-availability',
 			[ $this->availabilityController, 'renderPage' ],
 			'dashicons-clock',
-			31
+			41
 		);
 
 		// Studio admin / instructor: manage offerings.
@@ -113,7 +115,7 @@ class AdminMenu {
 			'us-policies',
 			[ $this->policyController, 'renderPage' ],
 			'dashicons-text-page',
-			34
+			31
 		);
 
 		// Studio admin: invite students to register.
@@ -124,7 +126,7 @@ class AdminMenu {
 			'us-invites',
 			[ $this->registrationController, 'renderPage' ],
 			'dashicons-email',
-			35
+			32
 		);
 
 		// Studio admin: all group-class enrolments.
@@ -146,7 +148,7 @@ class AdminMenu {
 			'us-students',
 			[ $this->studentController, 'renderPage' ],
 			'dashicons-id',
-			37
+			35
 		);
 
 		// Studio admin: confirm pending (e-transfer) payments.
@@ -157,7 +159,7 @@ class AdminMenu {
 			'us-payments',
 			[ $this->paymentController, 'renderPage' ],
 			'dashicons-money-alt',
-			38
+			37
 		);
 
 		// Studio admin (all) / instructor (own): monthly payments report with HST.
@@ -169,7 +171,7 @@ class AdminMenu {
 			'us-reports',
 			[ $this->paymentReportController, 'renderPage' ],
 			'dashicons-chart-bar',
-			39
+			38
 		);
 
 		// Studio admin: Stripe credentials and billing settings.
@@ -180,7 +182,7 @@ class AdminMenu {
 			'us-settings',
 			[ $this->settings, 'renderPage' ],
 			'dashicons-admin-settings',
-			40
+			30
 		);
 
 		// Instructor: view their upcoming lessons.
@@ -191,7 +193,64 @@ class AdminMenu {
 			'us-my-lessons',
 			[ $this->lessonController, 'renderInstructorLessons' ],
 			'dashicons-welcome-learn-more',
-			32
+			42
 		);
 	}
+
+	/**
+	 * Insert sidebar separators around the studio menus so they sit visually
+	 * apart from the core WordPress items and split into three sections —
+	 * mirroring the dividers core uses. Each separator is only added when the user
+	 * can see a menu in the following section, to avoid orphaned dividers.
+	 *
+	 * Layout: [29] · setup (Settings/Policies/Invites/Offerings) · [34] ·
+	 * people & money (Students/Group Classes/Payments/Payment Report) · [39] ·
+	 * operations (Scheduler) and instructor menus.
+	 */
+	private function addStudioSeparators(): void {
+		$this->addSeparatorAt( 29, $this->userSeesStudioMenu() );
+		$this->addSeparatorAt( 34, $this->userSeesPeopleSection() );
+		$this->addSeparatorAt( 39, current_user_can( RoleManager::CAP_VIEW_ALL_LESSONS ) );
+	}
+
+	private function addSeparatorAt( int $position, bool $visible ): void {
+		if ( ! $visible ) {
+			return;
+		}
+
+		global $menu;
+		if ( ! is_array( $menu ) || isset( $menu[ $position ] ) ) {
+			return;
+		}
+
+		// phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited -- writing to $menu is the supported way to add an admin sidebar separator.
+		$menu[ $position ] = [ '', 'read', 'us-studio-separator-' . $position, '', 'wp-menu-separator' ];
+	}
+
+	private function userSeesPeopleSection(): bool {
+		return current_user_can( RoleManager::CAP_MANAGE_STUDENTS )
+			|| current_user_can( RoleManager::CAP_VIEW_ALL_LESSONS )
+			|| current_user_can( RoleManager::CAP_MANAGE_BILLING );
+	}
+
+	private function userSeesStudioMenu(): bool {
+		$caps = [
+			RoleManager::CAP_VIEW_ALL_LESSONS,
+			RoleManager::CAP_VIEW_LESSONS,
+			RoleManager::CAP_MANAGE_AVAILABILITY,
+			RoleManager::CAP_MANAGE_OFFERINGS,
+			RoleManager::CAP_MANAGE_QUESTIONS,
+			RoleManager::CAP_MANAGE_POLICIES,
+			RoleManager::CAP_MANAGE_STUDENTS,
+			RoleManager::CAP_MANAGE_BILLING,
+		];
+
+		foreach ( $caps as $cap ) {
+			if ( current_user_can( $cap ) ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
 }