From 6d9a2271780bdd15a212b69edcd5b7031f35cb74 Mon Sep 17 00:00:00 2001
From: "vivi-the-going-merry[bot]"
 <308115520+vivi-the-going-merry[bot]@users.noreply.github.com>
Date: Thu, 17 Sep 2026 17:32:05 -0600
Subject: [PATCH] Add distinct aria-label to SMTP page step-number landmarks

The Formidable > SMTP admin page renders two step-number <aside> badges
(Install, Setup). <aside> carries an implicit role="complementary", and
neither had an accessible name, tripping the IBM Equal Access
aria_complementary_labelled rule.

Closes Strategy11/formidable-pro#6698
---
 classes/controllers/FrmSMTPController.php     | 10 ++++---
 tests/phpunit/base/FrmUnitTest.php            | 27 +++++++++++++++++++
 tests/phpunit/misc/test_FrmSMTPController.php | 16 +++++++++++
 3 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/classes/controllers/FrmSMTPController.php b/classes/controllers/FrmSMTPController.php
index be9d5dbad7..a921a488bc 100644
--- a/classes/controllers/FrmSMTPController.php
+++ b/classes/controllers/FrmSMTPController.php
@@ -239,7 +239,7 @@ protected function output_section_step_install() {
 
 		printf(
 			'<section class="step step-install">
-				<aside class="num">
+				<aside class="num" aria-label="%8$s">
 					%1$s
 					<i class="loader hidden"></i>
 				</aside>
@@ -255,7 +255,8 @@ protected function output_section_step_install() {
 			esc_attr( $step['plugin'] ),
 			esc_attr( $step['button_class'] ),
 			esc_attr( $step['button_action'] ),
-			esc_html( $step['button_text'] )
+			esc_html( $step['button_text'] ),
+			esc_attr__( 'Step 1', 'formidable' )
 		);
 	}
 
@@ -284,7 +285,7 @@ protected function output_section_step_setup() {
 
 		printf(
 			'<section class="step step-setup %1$s">
-				<aside class="num">
+				<aside class="num" aria-label="%8$s">
 					%2$s
 					<i class="loader hidden"></i>
 				</aside>
@@ -300,7 +301,8 @@ protected function output_section_step_setup() {
 			esc_html__( 'Select and configure your mailer.', 'formidable' ),
 			esc_url( admin_url( $this->config['smtp_settings'] ) ),
 			esc_attr( $step['button_class'] ),
-			esc_html( $step['button_text'] )
+			esc_html( $step['button_text'] ),
+			esc_attr__( 'Step 2', 'formidable' )
 		);
 	}
 
diff --git a/tests/phpunit/base/FrmUnitTest.php b/tests/phpunit/base/FrmUnitTest.php
index 1dad220136..bedbad481e 100644
--- a/tests/phpunit/base/FrmUnitTest.php
+++ b/tests/phpunit/base/FrmUnitTest.php
@@ -843,4 +843,31 @@ protected function use_frm_role( $role ) {
 				break;
 		}
 	}
+
+	/**
+	 * Assert that every <aside> tag in some rendered HTML has a non-empty aria-label.
+	 * <aside> carries an implicit role="complementary", which the IBM Equal Access
+	 * checker flags as unlabelled complementary content otherwise (aria_complementary_labelled).
+	 *
+	 * @since x.x
+	 *
+	 * @param string $html
+	 * @param int    $expected_count Required so an empty/short match list fails loudly instead of
+	 *                               passing vacuously (assertNotContains passes on an empty array).
+	 *
+	 * @return void
+	 */
+	protected function assert_complementary_landmarks_are_labelled( $html, $expected_count ) {
+		preg_match_all( '/<aside\b[^>]*>/', $html, $matches );
+		$this->assertCount( $expected_count, $matches[0], 'Unexpected number of <aside> elements' );
+
+		$labels = array();
+
+		foreach ( $matches[0] as $aside_tag ) {
+			preg_match( '/aria-label="([^"]*)"/', $aside_tag, $label_match );
+			$labels[] = $label_match[1] ?? '';
+		}
+
+		$this->assertNotContains( '', $labels, 'Every complementary landmark needs a non-empty accessible name' );
+	}
 }
diff --git a/tests/phpunit/misc/test_FrmSMTPController.php b/tests/phpunit/misc/test_FrmSMTPController.php
index 3b14de0671..293f76303d 100644
--- a/tests/phpunit/misc/test_FrmSMTPController.php
+++ b/tests/phpunit/misc/test_FrmSMTPController.php
@@ -33,4 +33,20 @@ public function test_link_overrides_preexisting_utm_params_from_wp_mail_smtp() {
 		$this->assertStringNotContainsString( 'utm_campaign=liteplugin', $link, 'Our own campaign should override the pre-existing one' );
 		$this->assertStringContainsString( 'urllink=wpmailsmtp%2Ecom%2Flite%2Dupgrade', $link, 'The hand-obfuscated redirect target must survive the utm re-tagging untouched' );
 	}
+
+	/**
+	 * The SMTP page renders two step-number <aside> badges (Install, Setup). Both need a
+	 * non-empty accessible name or they violate the aria_complementary_labelled a11y rule.
+	 *
+	 * @covers FrmSMTPController::output
+	 */
+	public function test_output_has_labelled_complementary_landmarks() {
+		$controller = new FrmSMTPController();
+
+		ob_start();
+		$controller->output();
+		$html = ob_get_clean();
+
+		$this->assert_complementary_landmarks_are_labelled( $html, 2 );
+	}
 }