From 36fc3f01346727bedecbc1805f26dc245dafd5aa Mon Sep 17 00:00:00 2001
From: SkyZeroZx <73321943+SkyZeroZx@users.noreply.github.com>
Date: Mon, 31 Aug 2026 19:09:28 -0500
Subject: [PATCH] docs(docs-infra): improve update checkbox accessibility

Associate each recommendation with its checkbox so assistive technology has a descriptive label and non-interactive text toggles the control. Keep embedded links independently operable.

(cherry picked from commit d8e74e7d39f020655b2bef91b955bd9cace14c6d)
---
 .../app/features/update/update.component.html | 24 ++++++++++++++-----
 .../app/features/update/update.component.scss |  1 +
 .../app/features/update/update.component.ts   | 12 ++++++++++
 3 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/adev/src/app/features/update/update.component.html b/adev/src/app/features/update/update.component.html
index c143eedff7e..163a6ed63e2 100644
--- a/adev/src/app/features/update/update.component.html
+++ b/adev/src/app/features/update/update.component.html
@@ -147,8 +147,12 @@
       <h3>Before you update</h3>
       @for (r of beforeRecommendations; track $index) {
         <div class="adev-recommendation-item">
-          <mat-checkbox />
-          <div class="adev-recommendation-content">
+          <mat-checkbox #checkbox [aria-labelledby]="'adev-before-recommendation-' + $index" />
+          <div
+            class="adev-recommendation-content"
+            [id]="'adev-before-recommendation-' + $index"
+            (click)="toggleRecommendation($event, checkbox)"
+          >
             <div [innerHTML]="r.renderedStep"></div>
             <span class="adev-complexity-badge" [class]="'adev-complexity-' + r.level">
               {{ getComplexityLevelName(r.level) }}
@@ -171,8 +175,12 @@
 
       @for (r of duringRecommendations; track $index) {
         <div class="adev-recommendation-item">
-          <mat-checkbox />
-          <div class="adev-recommendation-content">
+          <mat-checkbox #checkbox [aria-labelledby]="'adev-during-recommendation-' + $index" />
+          <div
+            class="adev-recommendation-content"
+            [id]="'adev-during-recommendation-' + $index"
+            (click)="toggleRecommendation($event, checkbox)"
+          >
             <div [innerHTML]="r.renderedStep"></div>
             <span class="adev-complexity-badge" [class]="'adev-complexity-' + r.level">
               {{ getComplexityLevelName(r.level) }}
@@ -189,8 +197,12 @@
       <h3>After you update</h3>
       @for (r of afterRecommendations; track $index) {
         <div class="adev-recommendation-item">
-          <mat-checkbox />
-          <div class="adev-recommendation-content">
+          <mat-checkbox #checkbox [aria-labelledby]="'adev-after-recommendation-' + $index" />
+          <div
+            class="adev-recommendation-content"
+            [id]="'adev-after-recommendation-' + $index"
+            (click)="toggleRecommendation($event, checkbox)"
+          >
             <div [innerHTML]="r.renderedStep"></div>
             <span class="adev-complexity-badge" [class]="'adev-complexity-' + r.level">
               {{ getComplexityLevelName(r.level) }}
diff --git a/adev/src/app/features/update/update.component.scss b/adev/src/app/features/update/update.component.scss
index 968e47de00a..1a5e043da1b 100644
--- a/adev/src/app/features/update/update.component.scss
+++ b/adev/src/app/features/update/update.component.scss
@@ -137,6 +137,7 @@ h4 {
     align-items: center;
     justify-content: space-between;
     gap: 1rem;
+    cursor: pointer;
   }
 
   .adev-complexity-badge {
diff --git a/adev/src/app/features/update/update.component.ts b/adev/src/app/features/update/update.component.ts
index 6445d9188cc..f0814b62d83 100644
--- a/adev/src/app/features/update/update.component.ts
+++ b/adev/src/app/features/update/update.component.ts
@@ -154,6 +154,18 @@ export default class UpdateComponent {
     }
   }
 
+  protected toggleRecommendation(event: MouseEvent, checkbox: MatCheckbox): void {
+    const target = event.target as Element | null;
+
+    // Keep links in the recommendation independently operable.
+    if (target?.closest('a')) {
+      return;
+    }
+
+    checkbox.toggle();
+    checkbox.focus();
+  }
+
   async showUpdatePath() {
     this.beforeRecommendations = [];
     this.duringRecommendations = [];