From 73a6c0a333c4d38fc242ec87d32381fceb313536 Mon Sep 17 00:00:00 2001
From: Jonathan Young <jonathan.young@digital.cabinet-office.gov.uk>
Date: Wed, 23 Nov 2022 09:41:46 +0000
Subject: [PATCH] Add aria controls and describedby

This commit adds the aria-controls and aria-describedby
attribute options to the button presenter. This will improve the
usability of the button component for users of screenreaders.
It also adds associated tests.
---
 CHANGELOG.md                                         |  2 ++
 .../components/docs/button.yml                       | 10 ++++++++++
 .../presenters/button_helper.rb                      |  8 +++++++-
 spec/components/button_spec.rb                       | 12 ++++++++++++
 4 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 88c21a6712..b3f2b8042b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,8 @@
 * Update to LUX 304 ([PR #3070](https://github.com/alphagov/govuk_publishing_components/pull/3070))
 * Set attributes for single page notification button based on Account API response ([PR #3071](https://github.com/alphagov/govuk_publishing_components/pull/3071))
 * Support custom text for the single page notification button component ([PR #2935](https://github.com/alphagov/govuk_publishing_components/pull/2935))
+* Add `aria-controls` and `aria-describedby` attribute options to the button component
+
 
 ## 32.1.0
 
diff --git a/app/views/govuk_publishing_components/components/docs/button.yml b/app/views/govuk_publishing_components/components/docs/button.yml
index 1fef780be4..8b963ff059 100644
--- a/app/views/govuk_publishing_components/components/docs/button.yml
+++ b/app/views/govuk_publishing_components/components/docs/button.yml
@@ -129,3 +129,13 @@ examples:
     data:
       text: Button
       aria_label: Button with custom label
+  with_aria_controls:
+    description: Used to identify what element(s) the button controls, this can be useful for users with visual impairment. In the example shown, the button controls the page wrapper with ID `wrapper` but it could be another identifying attribute.
+    data:
+      text: Button
+      aria_controls: wrapper
+  with_aria_describedby:
+    description: Can be used to give context to a button, this will be read after aria-label by a screenreader
+    data:
+      text: Button
+      aria_describedby: with_aria_describedby
diff --git a/lib/govuk_publishing_components/presenters/button_helper.rb b/lib/govuk_publishing_components/presenters/button_helper.rb
index bc257e23fa..08dd56af30 100644
--- a/lib/govuk_publishing_components/presenters/button_helper.rb
+++ b/lib/govuk_publishing_components/presenters/button_helper.rb
@@ -23,7 +23,9 @@ class ButtonHelper
                   :name,
                   :value,
                   :classes,
-                  :aria_label
+                  :aria_label,
+                  :aria_controls,
+                  :aria_describedby
 
       def initialize(local_assigns)
         @href = local_assigns[:href]
@@ -52,6 +54,8 @@ def initialize(local_assigns)
         @aria_label = local_assigns[:aria_label]
         @info_text_id = "info-text-id-#{SecureRandom.hex(4)}"
         @button_id = "button-id-#{SecureRandom.hex(4)}"
+        @aria_controls = local_assigns[:aria_controls]
+        @aria_describedby = local_assigns[:aria_describedby]
       end
 
       def link?
@@ -90,6 +94,8 @@ def html_options
         options[:name] = name if name.present? && value.present?
         options[:value] = value if name.present? && value.present?
         options[:aria] = { label: aria_label } if aria_label
+        options[:aria][:controls] =  aria_controls if aria_controls
+        options[:aria][:describedby] = aria_describedby if aria_describedby
         options[:draggable] = false if link?
         options
       end
diff --git a/spec/components/button_spec.rb b/spec/components/button_spec.rb
index f0585948aa..e83c04d462 100644
--- a/spec/components/button_spec.rb
+++ b/spec/components/button_spec.rb
@@ -231,4 +231,16 @@ def component_name
 
     assert_select '.gem-c-button[aria-label="Button with custom label"]'
   end
+
+  it "renders with aria-controls" do
+    render_component(text: "Button", aria_controls: "Testing aria-controls")
+
+    assert_select '.gem-c-button[aria-controls="Testing aria-controls"]'
+  end
+
+  it "renders with aria-describedby" do
+    render_component(text: "Button", aria_describedby: "Testing aria-describedby")
+
+    assert_select '.gem-c-button[aria-describedby="Testing aria-describedby"]'
+  end
 end