Add docs covering visually hidden helper standalone

app/helpers/govuk_visually_hidden_helper.rb

@@ -1,10 +1,12 @@
 module GovukVisuallyHiddenHelper
-  def govuk_visually_hidden(text, focusable: false)
-    return if text.nil?
+  def govuk_visually_hidden(text = nil, focusable: false, &block)
+    content = (block_given?) ? block.call : text
+
+    return if content.blank?
 
     visually_hidden_class = focusable ? "govuk-visually-hidden-focusable" : "govuk-visually-hidden"
 
-    tag.span(text, class: visually_hidden_class)
+    tag.span(content, class: visually_hidden_class)
   end
 end
 

guide/content/helpers/visually-hidden-text.slim

@@ -1,3 +1,25 @@
 ---
 title: Visually hidden text
 ---
+
+markdown:
+  Most of the time content should be both visible on the screen and availble to
+  screen readers. However, somtimes when space is at a premium, we may want
+  to hide text that would clutter the screen. This puts users of assistive
+  technology like screen readers at a disadvantage.
+
+  We can hide content but make it available to users of assistive technology
+  using the `govuk-visually-hidden` class. This library provides a helper method
+  which makes hiding content easier.
+
+== render('/partials/example.*',
+  caption: "Setting visually hidden text with an argument",
+  code: visually_hidden_text_via_argument)
+
+== render('/partials/example.*',
+  caption: "Setting visually hidden text with a block",
+  code: visually_hidden_text_via_block)
+
+== render('/partials/example.*',
+  caption: "Focusable visually hidden text",
+  code: focusable_visually_hidden_text)

guide/lib/examples/visually_hidden_helpers.rb

@@ -0,0 +1,37 @@
+module Examples
+  module VisuallyHiddenHelpers
+    def visually_hidden_text_via_argument
+      <<~SNIPPET
+        p Regular text
+
+        = govuk_visually_hidden("This content is visually hidden")
+
+        p More regular text
+      SNIPPET
+    end
+
+    def visually_hidden_text_via_block
+      <<~SNIPPET
+        p Regular text
+
+        = govuk_visually_hidden do
+          p This paragraph is visually hidden
+
+        p More regular text
+      SNIPPET
+    end
+
+    def focusable_visually_hidden_text
+      <<~SNIPPET
+        p Regular text
+
+        p
+          a href="#"
+            | Some link
+            = govuk_visually_hidden("Focus on me", focusable: true)
+
+        p More regular text
+      SNIPPET
+    end
+  end
+end

guide/lib/helpers.rb

@@ -117,6 +117,7 @@ class Application < Rails::Application; end
 use_helper Examples::CommonOptionsHelpers
 use_helper Examples::BackToTopLinkHelpers
 use_helper Examples::TitleWithErrorPrefixHelpers
+use_helper Examples::VisuallyHiddenHelpers
 
 ActiveSupport.on_load(:action_view) { include GovukVisuallyHiddenHelper }
 ActiveSupport.on_load(:action_view) { include GovukLinkHelper }