Support inserting visually hidden text into links

Often it's useful to provide a little extra context for screen reader
users by adding visually hidden text to links and buttons. This is
already possible using blocks but it's simpler to add them with keyword
arguments

app/helpers/govuk_link_helper.rb

@@ -3,30 +3,30 @@
 module GovukLinkHelper
   using HTMLAttributesUtils
 
-  def govuk_link_to(name, href = nil, new_tab: false, inverse: false, muted: false, no_underline: false, no_visited_state: false, text_colour: false, **kwargs, &block)
+  def govuk_link_to(name, href = nil, new_tab: false, inverse: false, muted: false, no_underline: false, no_visited_state: false, text_colour: false, visually_hidden_prefix: nil, visually_hidden_suffix: nil, **kwargs, &block)
     link_args = extract_link_args(new_tab: new_tab, inverse: inverse, muted: muted, no_underline: no_underline, no_visited_state: no_visited_state, text_colour: text_colour, **kwargs)
-    link_text = (block_given?) ? block.call : name
+    link_text = build_text(name, visually_hidden_prefix: visually_hidden_prefix, visually_hidden_suffix: visually_hidden_suffix, &block)
 
     link_to(link_text, href, **link_args)
   end
 
-  def govuk_mail_to(email_address, name = nil, new_tab: false, inverse: false, muted: false, no_underline: false, no_visited_state: false, text_colour: false, **kwargs, &block)
+  def govuk_mail_to(email_address, name = nil, new_tab: false, inverse: false, muted: false, no_underline: false, no_visited_state: false, text_colour: false, visually_hidden_prefix: nil, visually_hidden_suffix: nil, **kwargs, &block)
     link_args = extract_link_args(new_tab: new_tab, inverse: inverse, muted: muted, no_underline: no_underline, no_visited_state: no_visited_state, text_colour: text_colour, **kwargs)
-    link_text = (block_given?) ? block.call : name
+    link_text = build_text(name, visually_hidden_prefix: visually_hidden_prefix, visually_hidden_suffix: visually_hidden_suffix, &block)
 
     mail_to(email_address, link_text, **link_args)
   end
 
-  def govuk_button_to(name, href = nil, disabled: false, inverse: false, secondary: false, warning: false, **kwargs, &block)
+  def govuk_button_to(name, href = nil, disabled: false, inverse: false, secondary: false, warning: false, visually_hidden_prefix: nil, visually_hidden_suffix: nil, **kwargs, &block)
     button_args = extract_button_args(new_tab: false, disabled: disabled, inverse: inverse, secondary: secondary, warning: warning, **kwargs)
-    button_text = (block_given?) ? block.call : name
+    button_text = build_text(name, visually_hidden_prefix: visually_hidden_prefix, visually_hidden_suffix: visually_hidden_suffix, &block)
 
     button_to(button_text, href, **button_args)
   end
 
-  def govuk_button_link_to(name, href = nil, new_tab: false, disabled: false, inverse: false, secondary: false, warning: false, **kwargs, &block)
+  def govuk_button_link_to(name, href = nil, new_tab: false, disabled: false, inverse: false, secondary: false, warning: false, visually_hidden_prefix: nil, visually_hidden_suffix: nil, **kwargs, &block)
     button_args = extract_button_link_args(new_tab: new_tab, disabled: disabled, inverse: inverse, secondary: secondary, warning: warning, **kwargs)
-    button_text = (block_given?) ? block.call : name
+    button_text = build_text(name, visually_hidden_prefix: visually_hidden_prefix, visually_hidden_suffix: visually_hidden_suffix, &block)
 
     link_to(button_text, href, **button_args)
   end
@@ -122,6 +122,19 @@ def extract_button_classes(inverse: false, secondary: false, warning: false)
   def brand
     Govuk::Components.brand
   end
+
+  def build_text(original, visually_hidden_prefix:, visually_hidden_suffix:, &block)
+    text = (block_given?) ? block.call : original
+
+    safe_join(
+      [
+        govuk_visually_hidden(visually_hidden_prefix),
+        text,
+        govuk_visually_hidden(visually_hidden_suffix),
+      ].compact,
+      " "
+    )
+  end
 end
 
 ActiveSupport.on_load(:action_view) { include GovukLinkHelper }

spec/helpers/govuk_link_helper_spec.rb

@@ -86,6 +86,36 @@
       end
     end
 
+    context "when visually_hidden_prefix: 'some text'" do
+      let(:visually_hidden_prefix) { "some prefix" }
+      let(:kwargs) { { visually_hidden_prefix: visually_hidden_prefix } }
+
+      specify "the prefix is present and visually hidden" do
+        expect(subject).to have_tag("a", text: /hello/, with: { href: "/world", class: "govuk-link" }) do
+          with_tag("span", text: visually_hidden_prefix)
+        end
+      end
+
+      specify "the prefix is before the text" do
+        expect(subject).to match(%(#{visually_hidden_prefix}.*hello))
+      end
+    end
+
+    context "when visually_hidden_suffix: 'some text'" do
+      let(:visually_hidden_suffix) { "some suffix" }
+      let(:kwargs) { { visually_hidden_suffix: visually_hidden_suffix } }
+
+      specify "the suffix is present and visually hidden" do
+        expect(subject).to have_tag("a", text: /hello/, with: { href: "/world", class: "govuk-link" }) do
+          with_tag("span", text: visually_hidden_suffix, class: "govuk-visually-hidden")
+        end
+      end
+
+      specify "the suffix is after the text" do
+        expect(subject).to match(%(hello.*#{visually_hidden_suffix}))
+      end
+    end
+
     # the link modifiers text_colour, inverse, muted all change the link's text colour
     # and shouldn't be used together
     describe "invalid combinations" do
@@ -173,6 +203,36 @@
       end
     end
 
+    context "when visually_hidden_prefix: 'some text'" do
+      let(:visually_hidden_prefix) { "some prefix" }
+      let(:kwargs) { { visually_hidden_prefix: visually_hidden_prefix } }
+
+      specify "the prefix is present and visually hidden" do
+        expect(subject).to have_tag("a", text: /hello/, with: { href: "mailto:world@solar.system", class: "govuk-link" }) do
+          with_tag("span", text: visually_hidden_prefix)
+        end
+      end
+
+      specify "the prefix is before the text" do
+        expect(subject).to match(%(#{visually_hidden_prefix}.*hello))
+      end
+    end
+
+    context "when visually_hidden_suffix: 'some text'" do
+      let(:visually_hidden_suffix) { "some suffix" }
+      let(:kwargs) { { visually_hidden_suffix: visually_hidden_suffix } }
+
+      specify "the suffix is present and visually hidden" do
+        expect(subject).to have_tag("a", text: /hello/, with: { href: "mailto:world@solar.system", class: "govuk-link" }) do
+          with_tag("span", text: visually_hidden_suffix, class: "govuk-visually-hidden")
+        end
+      end
+
+      specify "the suffix is after the text" do
+        expect(subject).to match(%(hello.*#{visually_hidden_suffix}))
+      end
+    end
+
     # the link modifiers text_colour, inverse, muted all change the link's text colour
     # and shouldn't be used together
     describe "invalid combinations" do
@@ -274,6 +334,36 @@
       end
     end
 
+    context "when visually_hidden_prefix: 'some text'" do
+      let(:visually_hidden_prefix) { "some prefix" }
+      let(:kwargs) { { visually_hidden_prefix: visually_hidden_prefix } }
+
+      specify "the prefix is present and visually hidden" do
+        expect(subject).to have_tag("a", text: /hello/, with: { href: "/world", class: "govuk-button" }) do
+          with_tag("span", text: visually_hidden_prefix)
+        end
+      end
+
+      specify "the prefix is before the text" do
+        expect(subject).to match(%(#{visually_hidden_prefix}.*hello))
+      end
+    end
+
+    context "when visually_hidden_suffix: 'some text'" do
+      let(:visually_hidden_suffix) { "some suffix" }
+      let(:kwargs) { { visually_hidden_suffix: visually_hidden_suffix } }
+
+      specify "the suffix is present and visually hidden" do
+        expect(subject).to have_tag("a", text: /hello/, with: { href: "/world", class: "govuk-button" }) do
+          with_tag("span", text: visually_hidden_suffix, class: "govuk-visually-hidden")
+        end
+      end
+
+      specify "the suffix is after the text" do
+        expect(subject).to match(%(hello.*#{visually_hidden_suffix}))
+      end
+    end
+
     # a button can be disabled in combination with other styles but cannot
     # be called with more than one of eitehr warning, inverse or secondary
     describe "invalid combinations" do
@@ -377,6 +467,40 @@
       end
     end
 
+    context "when visually_hidden_prefix: 'some text'" do
+      let(:visually_hidden_prefix) { "some prefix" }
+      let(:kwargs) { { visually_hidden_prefix: visually_hidden_prefix } }
+
+      specify "the prefix is present and visually hidden" do
+        expect(subject).to have_tag("form", with: { method: "post", action: "/world" }) do
+          with_tag("button", text: /hello/, with: { class: %w[govuk-button] }) do
+            with_tag("span", text: visually_hidden_prefix)
+          end
+        end
+      end
+
+      specify "the prefix is before the text" do
+        expect(subject).to match(%(#{visually_hidden_prefix}.*hello))
+      end
+    end
+
+    context "when visually_hidden_suffix: 'some text'" do
+      let(:visually_hidden_suffix) { "some suffix" }
+      let(:kwargs) { { visually_hidden_suffix: visually_hidden_suffix } }
+
+      specify "the suffix is present and visually hidden" do
+        expect(subject).to have_tag("form", with: { method: "post", action: "/world" }) do
+          with_tag("button", text: /hello/, with: { class: %w[govuk-button] }) do
+            with_tag("span", text: visually_hidden_suffix, class: "govuk-visually-hidden")
+          end
+        end
+      end
+
+      specify "the suffix is after the text" do
+        expect(subject).to match(%(hello.*#{visually_hidden_suffix}))
+      end
+    end
+
     # a button can be disabled in combination with other styles but cannot
     # be called with more than one of eitehr warning, inverse or secondary
     describe "invalid combinations" do