crown_marketplace_utils 0.1.0.beta.1 → 0.1.0.beta.3

data/lib/crown_marketplace_utils/gov_uk_helper/label.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+module CrownMarketplaceUtils
+  module GovUkHelper
+    # = GOV.UK label
+    #
+    # This helper is used for generating the label component from the Government Design Systems
+
+    module Label
+      include ActionView::Context
+      include ActionView::Helpers::TagHelper
+      include ActionView::Helpers::TextHelper
+      include ActionView::Helpers::FormTagHelper
+
+      # Generates the HTML for the GOV.UK label component
+      #
+      # @param attribute [String, Symbol] the attribute of the input that requires a label
+      # @param label_text [String] the label text, it is ignored if a block is given
+      # @param govuk_label_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_label_options [String] :classes additional CSS classes for the label HTML
+      # @option govuk_label_options [Boolean] :is_page_heading (false) if the legend is also the heading it will rendered in a h1
+      # @option govuk_label_options [Hash] :attributes ({}) any additional attributes that will added as part of the HTML
+      #
+      # @yield HTML that will be contained within the 'govuk-label' label
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Label
+      #                                     which can then be rendered on the page
+
+      def govuk_label(attribute, label_text = nil, **govuk_label_options)
+        _govuk_label(**govuk_label_options) do |govuk_label_classes, govuk_label_attributes|
+          label_tag(attribute, class: govuk_label_classes, **govuk_label_attributes) do
+            if block_given?
+              yield
+            else
+              concat(label_text)
+            end
+          end
+        end
+      end
+
+      # Generates the HTML for the GOV.UK label component using an ActionView::Helpers::FormBuilder
+      #
+      # @param form [ActionView::Helpers::FormBuilder] :form the form builder used to create the label
+      # @param attribute [String, Symbol] the attribute of the input that requires a label
+      # @param label_text [String] the label text, it is ignored if a block is given
+      # @param govuk_label_options [Hash] options that will be used in customising the HTML
+      #
+      # @option (see govuk_label)
+      #
+      # @yield (see govuk_label)
+      #
+      # @return (see govuk_label)
+
+      def govuk_label_with_form(form, attribute, label_text = nil, **govuk_label_options, &block)
+        _govuk_label(**govuk_label_options) do |govuk_label_classes, govuk_label_attributes|
+          if block_given?
+            form.label(attribute, class: govuk_label_classes, **govuk_label_attributes, &block)
+          else
+            form.label(attribute, label_text, class: govuk_label_classes, **govuk_label_attributes)
+          end
+        end
+      end
+
+      private
+
+      # Wrapper method used by {#govuk_label} and {#govuk_label_with_form} to generate the Label HTML
+      #
+      # @param govuk_label_options [Hash] options that will be used in customising the HTML
+      #
+      # @option (see govuk_label)
+      #
+      # @yield the label HTML generated by {#govuk_label} or {#govuk_label_with_form}
+      #
+      # @yieldparam govuk_label_classes [Array] the classes for the label HTML
+      # @yieldparam govuk_label_attributes [Hash] additional attributes that will added as part of the HTML
+      #
+      # @return (see govuk_label)
+
+      def _govuk_label(**govuk_label_options)
+        govuk_label_classes = ['govuk-label']
+        govuk_label_classes << govuk_label_options[:classes]
+        govuk_label_options[:attributes] ||= {}
+
+        label_html = yield(govuk_label_classes, govuk_label_options[:attributes])
+
+        if govuk_label_options[:is_page_heading]
+          tag.h1(label_html, class: 'govuk-label-wrapper')
+        else
+          label_html
+        end
+      end
+    end
+  end
+end

data/lib/crown_marketplace_utils/gov_uk_helper/notification_banner.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+module CrownMarketplaceUtils
+  module GovUkHelper
+    # = GOV.UK Notification Banner
+    #
+    # This helper is used for generating the notification banner component from the
+    # {https://design-system.service.gov.uk/components/notification-banner GDS - Components - Notification banner}
+
+    module NotificationBanner
+      include ActionView::Context
+      include ActionView::Helpers::TagHelper
+      include ActionView::Helpers::TextHelper
+
+      # Generates the HTML for the GOV.UK Notification banner component
+      #
+      # @param text [String] the text that will be used for the heading in the content section of the banner.
+      #                      It is ignored if a block is given
+      # @param success_banner [Boolean] will use the success banner options if this is set to true
+      # @param govuk_notification_banner_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_notification_banner_options [String] :classes additional CSS classes for the notification banner HTML
+      # @option govuk_notification_banner_options [String] :title_text ('Important') the title text shown at the top of the banner
+      # @option govuk_notification_banner_options [String] :title_id ('govuk-notification-banner-title') the ID for the title text
+      # @option govuk_notification_banner_options [String] :role ('region') the role for the banner
+      # @option govuk_notification_banner_options [String] :heading_level (2) the heading level for the title text
+      # @option govuk_notification_banner_options [Hash] :attributes ({data: { module: 'govuk-notification-banner' }, aria: { labelledby: 'govuk-notification-banner-title' }})
+      #                                                  any additional attributes that will added as part of the HTML
+      #
+      # @yield HTML that will be contained within the 'govuk-notification-banner__content' div
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Notification banner
+      #                                     which can then be rendered on the page
+
+      def govuk_notification_banner(text = nil, success_banner = false, **govuk_notification_banner_options)
+        banner_options = fetch_banner_options(success_banner, govuk_notification_banner_options)
+        govuk_notification_banner_classes = fetch_banner_classes(banner_options, govuk_notification_banner_options)
+        govuk_notification_banner_attributes = fetch_banner_attributes(banner_options, govuk_notification_banner_options)
+
+        tag.div(class: govuk_notification_banner_classes, role: banner_options[:role], **govuk_notification_banner_attributes) do
+          capture do
+            concat(tag.div(class: 'govuk-notification-banner__header') do
+              tag.send(:"h#{govuk_notification_banner_options[:heading_level] || 2}", banner_options[:title_text], class: 'govuk-notification-banner__title', id: banner_options[:title_id])
+            end)
+            concat(tag.div(class: 'govuk-notification-banner__content') do
+              if block_given?
+                yield
+              else
+                tag.p(text, class: 'govuk-notification-banner__heading')
+              end
+            end)
+          end
+        end
+      end
+
+      private
+
+      # Determines the banner options to be used for {#govuk_notification_banner}
+      #
+      # @param success_banner [Boolean] will use the success banner options if this is set to true
+      # @param govuk_notification_banner_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_notification_banner_options [String] :title_text ('Important') the title text shown at the top of the banner
+      # @option govuk_notification_banner_options [String] :title_id ('govuk-notification-banner-title') the ID for the title text
+      # @option govuk_notification_banner_options [String] :role ('region') the role for the banner
+      #
+      # @return [Hash] contains the following options used in {#govuk_notification_banner}:
+      #                - +classes+
+      #                - +title_text+
+      #                - +title_id+
+      #                - +role+
+
+      def fetch_banner_options(success_banner, govuk_notification_banner_options)
+        banner_options = DEFAULT_OPTIONS.dup
+
+        banner_options.merge!(SUCCESS_BANNER_OPTIONS) if success_banner
+
+        govuk_notification_banner_options.each do |key, value|
+          banner_options[key] = value if banner_options.key?(key)
+        end
+
+        banner_options
+      end
+
+      # Determines the banner classes to be used for {#govuk_notification_banner}
+      #
+      # @param banner_options [Hash] this is the return value from {#fetch_banner_options}
+      # @param govuk_notification_banner_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_notification_banner_options [String] :classes additional CSS classes for the notification banner HTML
+      #
+      # @return [Array<String>] an array of classes to be used in {#govuk_notification_banner}
+
+      def fetch_banner_classes(banner_options, govuk_notification_banner_options)
+        govuk_notification_banner_classes = ['govuk-notification-banner']
+        govuk_notification_banner_classes << govuk_notification_banner_options[:classes]
+        govuk_notification_banner_classes << banner_options[:classes]
+
+        govuk_notification_banner_classes
+      end
+
+      # Default HTML attributes for {#govuk_notification_banner}
+      #
+      # @param banner_options [Hash] this is the return value from {#fetch_banner_options}
+      # @param govuk_notification_banner_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_notification_banner_options [Hash] :attributes ({data: { module: 'govuk-notification-banner' }, aria: { labelledby: 'govuk-notification-banner-title' }})
+      #                                                  any additional attributes that will added as part of the HTML
+      #
+      # @return [Hash] contains the default attributes for {#govuk_notification_banner} and any additional attributes that were passed
+
+      def fetch_banner_attributes(banner_options, govuk_notification_banner_options)
+        govuk_notification_banner_attributes = govuk_notification_banner_options[:attributes] || {}
+        (govuk_notification_banner_attributes[:data] ||= {}).merge!({ module: 'govuk-notification-banner' })
+        (govuk_notification_banner_attributes[:aria] ||= {}).merge!({ labelledby: banner_options[:title_id] })
+
+        govuk_notification_banner_attributes
+      end
+
+      # Default options used in normal versions of {#govuk_notification_banner}
+
+      DEFAULT_OPTIONS = {
+        title_text: 'Important',
+        title_id: 'govuk-notification-banner-title',
+        role: 'region'
+      }.freeze
+
+      # Options specific for the success version of {#govuk_notification_banner}
+
+      SUCCESS_BANNER_OPTIONS = {
+        classes: 'govuk-notification-banner--success',
+        title_text: 'Success',
+        role: 'alert'
+      }.freeze
+    end
+  end
+end

data/lib/crown_marketplace_utils/gov_uk_helper/pagination.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+module CrownMarketplaceUtils
+  module GovUkHelper
+    # = GOV.UK Pagination
+    #
+    # This helper is used for generating the pagination component from the
+    # {https://design-system.service.gov.uk/components/pagination GDS - Components - Pagination}
+
+    module Pagination
+      include ActionView::Context
+      include ActionView::Helpers::TagHelper
+      include ActionView::Helpers::TextHelper
+      include ActionView::Helpers::UrlHelper
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # Generates the HTML for the GOV.UK Pagination component
+      #
+      # @param govuk_pagination_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_pagination_options [String] :classes additional CSS classes for the pagination HTML
+      # @option govuk_pagination_options [Array] :items an array of items for the pagination (see: {govuk_pagination_items})
+      # @option govuk_pagination_options [Hash] :previous the previous link (see: {govuk_pagination_previous})
+      # @option govuk_pagination_options [Hash] :next the next link (see: {govuk_pagination_next})
+      # @option govuk_pagination_options [Hash] :attributes ({role: 'navigation', aria: { label: 'results' }})
+      #                                         any additional attributes that will added as part of the HTML
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Pagination
+      #                                     which can then be rendered on the page
+
+      def govuk_pagination(**govuk_pagination_options)
+        govuk_pagination_classes = ['govuk-pagination']
+        govuk_pagination_classes << govuk_pagination_options[:classes]
+
+        block_is_level = govuk_pagination_options[:items].blank? && (govuk_pagination_options[:next].present? || govuk_pagination_options[:previous].present?)
+
+        govuk_pagination_classes << 'govuk-pagination--block' if block_is_level
+
+        (govuk_pagination_options[:attributes] ||= {}).merge({ role: 'navigation' })
+        (govuk_pagination_options[:attributes][:aria] ||= {})[:label] ||= 'results'
+
+        tag.nav(class: govuk_pagination_classes, **govuk_pagination_options[:attributes]) do
+          capture do
+            concat(govuk_pagination_previous(block_is_level, **govuk_pagination_options[:previous])) if govuk_pagination_options[:previous]
+            concat(govuk_pagination_items(govuk_pagination_options[:items])) if govuk_pagination_options[:items]
+            concat(govuk_pagination_next(block_is_level, **govuk_pagination_options[:next])) if govuk_pagination_options[:next]
+          end
+        end
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      private
+
+      # Generates the previous link for {govuk_pagination}
+      #
+      # @param block_is_level [Boolean] when there are no items, this will be true and will add extra classe
+      #                                 to the link to make the next and previous pagination links level
+      # @param govuk_pagination_previous_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_pagination_previous_options [String] :href the URL for the link
+      # @option govuk_pagination_previous_options [String] :text ('Previous') the text for the link
+      # @option govuk_pagination_previous_options [String] :lable_text additional text for the link when the pagination block is level
+      # @option govuk_pagination_previous_options [Hash] :attributes ({}) any additional attributes that will added as part of the HTML
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the previous link which is used in {govuk_pagination}
+
+      def govuk_pagination_previous(block_is_level, **govuk_pagination_previous_options)
+        govuk_pagination_previous_classes = ['govuk-pagination__link-title']
+        govuk_pagination_previous_classes << 'govuk-pagination__link-title--decorated' if block_is_level && !govuk_pagination_previous_options[:lable_text]
+
+        tag.div(class: 'govuk-pagination__prev') do
+          link_to(govuk_pagination_previous_options[:href], class: 'govuk-link govuk-pagination__link', rel: 'prev', **(govuk_pagination_previous_options[:attributes] || {})) do
+            capture do
+              concat(govuk_pagination_icon(:prev))
+              concat(tag.span(govuk_pagination_previous_options[:text] || 'Previous', class: govuk_pagination_previous_classes))
+              concat(govuk_pagination_icon_label_text(block_is_level, govuk_pagination_previous_options[:lable_text]))
+            end
+          end
+        end
+      end
+
+      # Generates the next link for {govuk_pagination}
+      #
+      # @param block_is_level [Boolean] when there are no items, this will be true and will add extra classe
+      #                                 to the link to make the next and previous pagination links level
+      # @param govuk_pagination_next_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_pagination_next_options [String] :href the URL for the link
+      # @option govuk_pagination_next_options [String] :text ('Next') the text for the link
+      # @option govuk_pagination_next_options [String] :lable_text additional text for the link when the pagination block is level
+      # @option govuk_pagination_next_options [Hash] :attributes ({}) any additional attributes that will added as part of the HTML
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the next link which is used in {govuk_pagination}
+
+      def govuk_pagination_next(block_is_level, **govuk_pagination_next_options)
+        govuk_pagination_next_classes = ['govuk-pagination__link-title']
+        govuk_pagination_next_classes << 'govuk-pagination__link-title--decorated' if block_is_level && !govuk_pagination_next_options[:lable_text]
+
+        tag.div(class: 'govuk-pagination__next') do
+          link_to(govuk_pagination_next_options[:href], class: 'govuk-link govuk-pagination__link', rel: 'next', **(govuk_pagination_next_options[:attributes] || {})) do
+            capture do
+              concat(govuk_pagination_icon(:next)) if block_is_level
+              concat(tag.span(govuk_pagination_next_options[:text] || 'Next', class: govuk_pagination_next_classes))
+              concat(govuk_pagination_icon_label_text(block_is_level, govuk_pagination_next_options[:lable_text]))
+              concat(govuk_pagination_icon(:next)) unless block_is_level
+            end
+          end
+        end
+      end
+
+      # Generates the item links for {govuk_pagination}
+      #
+      # @param govuk_pagination_items [Array(Hash)] an array of item hashes for the pagination.
+      #                                             There are two types of item:
+      #                                             - {govuk_pagination_item_ellipsis ellipsis item}
+      #                                             - {govuk_pagination_item_number number item}
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the lits of items which is used in {govuk_pagination}
+
+      def govuk_pagination_items(govuk_pagination_items)
+        tag.ul(class: 'govuk-pagination__list') do
+          capture do
+            govuk_pagination_items.each do |govuk_pagination_item|
+              case govuk_pagination_item[:type]
+              when :ellipsis
+                concat(govuk_pagination_item_ellipsis)
+              when :number
+                concat(govuk_pagination_item_number(govuk_pagination_item))
+              end
+            end
+          end
+        end
+      end
+
+      # Generates the icon for:
+      # - {govuk_pagination_previous}
+      # - {govuk_pagination_next}
+      #
+      # @param type [Symbol] the type of the pagination icon (+:prev+ or +:next+)
+      #
+      # @return [ActiveSupport::SafeBuffer]
+
+      def govuk_pagination_icon(type)
+        tag.svg(class: "govuk-pagination__icon govuk-pagination__icon--#{type}", xmlns: 'http://www.w3.org/2000/svg', height: '13', width: '15', aria: { hidden: 'true' }, focusable: 'false', viewBox: '0 0 15 13') do
+          tag.path(d: PAGINATION_ICON_PATHS[type])
+        end
+      end
+
+      # Generates the label text for:
+      # - {govuk_pagination_previous}
+      # - {govuk_pagination_next}
+      #
+      # @param block_is_level [Boolean] when there are no items, this will be true
+      # @param label_text [String] the additional text for the link
+      #
+      # @return [ActiveSupport::SafeBuffer]
+
+      def govuk_pagination_icon_label_text(block_is_level, label_text)
+        return unless block_is_level && label_text
+
+        capture do
+          concat(tag.span(':', class: 'govuk-visually-hidden'))
+          concat(tag.span(label_text, class: 'govuk-pagination__link-label'))
+        end
+      end
+
+      # Generates the ellipsis HTML for {govuk_pagination_items}
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for an ellipsis item which is used in {govuk_pagination_items}
+
+      def govuk_pagination_item_ellipsis
+        tag.li('⋯', class: 'govuk-pagination__item govuk-pagination__item--ellipses')
+      end
+
+      # Generates the number item HTML for {govuk_pagination_items}
+      #
+      # @param govuk_pagination_item [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_pagination_item [String] :href the URL for the link
+      # @option govuk_pagination_item [String] :number the number for the link
+      # @option govuk_pagination_item [String] :current is this item the current page
+      # @option govuk_pagination_item [Hash] :attributes ({aria: { label: 'Page <NUMBER>' } })
+      #                                                  any additional attributes that will added as part of the HTML
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for an number item which is used in {govuk_pagination_items}
+
+      def govuk_pagination_item_number(govuk_pagination_item)
+        govuk_pagination_item_classes = ['govuk-pagination__item']
+        (govuk_pagination_item[:attributes] ||= {})[:aria] ||= {}
+        govuk_pagination_item[:attributes][:aria][:label] ||= "Page #{govuk_pagination_item[:number]}"
+
+        if govuk_pagination_item[:current]
+          govuk_pagination_item_classes << 'govuk-pagination__item--current'
+          govuk_pagination_item[:attributes][:aria][:current] = 'page'
+        end
+
+        tag.li(class: govuk_pagination_item_classes) do
+          link_to(govuk_pagination_item[:href], govuk_pagination_item[:number], class: 'govuk-link govuk-pagination__link', **govuk_pagination_item[:attributes])
+        end
+      end
+
+      # The paths for the pagination next and previous icons
+
+      PAGINATION_ICON_PATHS = {
+        prev: 'm6.5938-0.0078125-6.7266 6.7266 6.7441 6.4062 1.377-1.449-4.1856-3.9768h12.896v-2h-12.984l4.2931-4.293-1.414-1.414z',
+        next: 'm8.107-0.0078125-1.4136 1.414 4.2926 4.293h-12.986v2h12.896l-4.1855 3.9766 1.377 1.4492 6.7441-6.4062-6.7246-6.7266z'
+      }.freeze
+    end
+  end
+end

data/lib/crown_marketplace_utils/gov_uk_helper/step_by_step_navigation.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+module CrownMarketplaceUtils
+  module GovUkHelper
+    # = GOV.UK Step by step navigation
+    #
+    # This helper is used for generating the Step by step navigation component from the
+    # {https://design-system.service.gov.uk/patterns/step-by-step-navigation/ GDS - Pages - Step by step navigation}
+    #
+    # To use this component you need the following from {https://github.com/alphagov/govuk_publishing_components GOV.UK Publishing Components}.
+    # For the SCSS components you should add:
+    # - {https://github.com/alphagov/govuk_publishing_components/blob/main/app/assets/stylesheets/govuk_publishing_components/components/_step-by-step-nav.scss _step-by-step-nav.scss}
+    # - {https://github.com/alphagov/govuk_publishing_components/blob/main/app/assets/stylesheets/govuk_publishing_components/components/_step-by-step-nav-related.scss _step-by-step-nav-related.scss}
+    # - {https://github.com/alphagov/govuk_publishing_components/blob/main/app/assets/stylesheets/govuk_publishing_components/components/_step-by-step-nav-header.scss _step-by-step-nav-header.scss}
+    # For the JavaScript you should add:
+    # - {https://github.com/alphagov/govuk_publishing_components/blob/main/app/assets/javascripts/govuk_publishing_components/components/step-by-step-nav.js step-by-step-nav.js}
+
+    module StepByStepNavigation
+      include ActionView::Helpers
+      include ActionView::Context
+
+      # Generates the HTML for the GOV.UK Step by step navigation component (experimental)
+      #
+      # @param step_by_step_sections [Array] the navigation items that will be rendered to the page.
+      #                                   See {govuk_step_by_step_navigation_section} for more details
+      # @param govuk_step_by_step_navigation_options [Hash] options that will be used in customising the HTML
+      #
+      # @option govuk_step_by_step_navigation_options [String] :classes additional CSS classes for the step by step navigation HTML
+      # @option govuk_step_by_step_navigation_options [Hash] :attributes ({data: { module: 'govuk-step-by-step-navigation', 'show-text': 'Show', 'hide-text': 'Hide', 'show-all-text': 'Show all', 'hide-all-text': 'Hide all' } })
+      #                                                                  any additional attributes that will added as part of the HTML
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Step by step navigation
+      #                                     which can then be rendered on the page
+
+      def govuk_step_by_step_navigation(step_by_step_sections, **govuk_step_by_step_navigation_options)
+        govuk_step_by_step_navigation_classes = ['gem-c-step-nav gem-c-step-nav--large gem-c-step-nav--active']
+        govuk_step_by_step_navigation_classes << govuk_step_by_step_navigation_options[:classes]
+
+        tag.div(class: govuk_step_by_step_navigation_classes, **govuk_step_by_step_navigation_attributes(**govuk_step_by_step_navigation_options)) do
+          tag.ol(class: 'gem-c-step-nav__steps') do
+            capture do
+              step_by_step_sections.each.with_index(1) { |step_by_step_section, section_index| concat(govuk_step_by_step_navigation_section(step_by_step_section, section_index.to_s)) }
+            end
+          end
+        end
+      end
+
+      private
+
+      # The HTML for a section within GOV.UK Step by step navigation, used by {govuk_step_by_step_navigation}
+      #
+      # @param step_by_step_section [Hash] the parameters that will be used to create the section
+      # @param section_index [String] the index of the section
+      #
+      # @option step_by_step_section [Hash] :heading the paramaters for the section heading,
+      #                                              see {govuk_step_by_step_navigation_heading} for more details
+      # @option step_by_step_section [Array] :content the paramaters for the section content,
+      #                                               see {govuk_step_by_step_navigation_content} for more details
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Step by step navigation section
+      #                                     which is used in {govuk_step_by_step_navigation}
+
+      def govuk_step_by_step_navigation_section(step_by_step_section, section_index)
+        section_id = convert_to_id(step_by_step_section[:heading][:text])
+
+        tag.li(class: 'gem-c-step-nav__step js-step', id: section_id) do
+          capture do
+            concat(govuk_step_by_step_navigation_heading(step_by_step_section[:heading], section_index))
+            concat(govuk_step_by_step_navigation_content(step_by_step_section[:content], section_id, section_index))
+          end
+        end
+      end
+
+      # The HTML for a section heading within GOV.UK Step by step navigation, used by {govuk_step_by_step_navigation_section}
+      #
+      # @param section_heading [Hash] the parameters that will be used to create the heading
+      # @param section_index [String] the index of the section
+      #
+      # @option section_heading [Hash] :text text for the section heading
+      # @option section_heading [Hash] :logic (nil) text to show instead of a number in the sidebar
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Step by step navigation section heading
+      #                                     which is used in {govuk_step_by_step_navigation_section}
+
+      def govuk_step_by_step_navigation_heading(section_heading, section_index)
+        logic = section_heading[:logic]
+
+        tag.div(class: 'gem-c-step-nav__header js-toggle-panel', data: { position: section_index }) do
+          tag.h2(class: 'gem-c-step-nav__title') do
+            capture do
+              concat(tag.span(class: "gem-c-step-nav__circle gem-c-step-nav__circle--#{logic ? 'logic' : 'number'}") do
+                tag.span(class: 'gem-c-step-nav__circle-inner') do
+                  tag.span(class: 'gem-c-step-nav__circle-background') do
+                    capture do
+                      concat(tag.span('Step', class: 'govuk-visually-hidden'))
+                      concat(logic || section_index)
+                    end
+                  end
+                end
+              end)
+              concat(tag.span(class: 'js-step-title') do
+                tag.span(section_heading[:text], class: 'js-step-title-text')
+              end)
+            end
+          end
+        end
+      end
+
+      # The HTML for a section content within GOV.UK Step by step navigation, used by {govuk_step_by_step_navigation_section}
+      #
+      # @param content [Array] an array of the content items that will be rendered within the section.
+      #                        Only two types of content are allowed:
+      #                        - +:paragraph+ - see {govuk_step_by_step_navigation_paragraph}
+      #                        - +:list+ - see {govuk_step_by_step_navigation_list}
+      # @param section_id [String] the id of the section
+      # @param section_index [String] the index of the section
+      #
+      # @option content [Symbol] :type the type of content, either +:paragraph+ or +list+
+      # @option content [Symbol] :text the text for the paragraph. Ignored unless the +type+ is +:list+
+      # @option content [Symbol] :items the items for the list. Ignored unless the +type+ is +:paragraph+
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Step by step navigation section content
+      #                                     which is used in {govuk_step_by_step_navigation_section}
+
+      def govuk_step_by_step_navigation_content(content, section_id, section_index)
+        tag.div(class: 'gem-c-step-nav__panel js-panel', id: "step-panel-#{section_id}-#{section_index}") do
+          capture do
+            content.each do |element|
+              concat(
+                case element[:type]
+                when :paragraph
+                  govuk_step_by_step_navigation_paragraph(element[:text])
+                when :list
+                  govuk_step_by_step_navigation_list(element[:items])
+                end
+              )
+            end
+          end
+        end
+      end
+
+      # The HTML for the paragraph item within the GOV.UK Step by step navigation content, used by {govuk_step_by_step_navigation_content}
+      #
+      # @param text [String] the text for the paragraph
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the paragraph
+      #                                     which is used in {govuk_step_by_step_navigation_content}
+
+      def govuk_step_by_step_navigation_paragraph(text)
+        tag.p(
+          text,
+          class: 'gem-c-step-nav__paragraph',
+        )
+      end
+
+      # The HTML for the list items within the GOV.UK Step by step navigation content, used by {govuk_step_by_step_navigation_content}
+      #
+      # @param items [Array] an array of the list items,
+      #                      see {govuk_step_by_step_navigation_list_item} for more details
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the list
+      #                                     which is used in {govuk_step_by_step_navigation_content}
+
+      def govuk_step_by_step_navigation_list(items)
+        tag.ul(class: 'gem-c-step-nav__list gem-c-step-nav__list--choice', data: { length: items.length.to_s }) do
+          capture do
+            items.each do |item|
+              concat(govuk_step_by_step_navigation_list_item(item[:text], item[:no_marker]))
+            end
+          end
+        end
+      end
+
+      # The HTML for a list item, used by {govuk_step_by_step_navigation_list}
+      #
+      # @param text [Symbol] the text of the list item
+      # @param no_marker [Symbol] (nil) switch to hide the bullet marker
+      #
+      # @return [ActiveSupport::SafeBuffer] the HTML for the list item
+      #                                     which is used in {govuk_step_by_step_navigation_list}
+
+      def govuk_step_by_step_navigation_list_item(text, no_marker)
+        list_item_classes = ['gem-c-step-nav__list-item js-list-item']
+        list_item_classes << 'gem-c-step-nav__list--no-marker' if no_marker
+
+        tag.li(class: list_item_classes) do
+          tag.span(text)
+        end
+      end
+
+      # Converts the title text into a string to be used as the section id
+      #
+      # @param title [String] the section title that will be converted
+      #
+      # @return [String] the section id
+
+      def convert_to_id(title)
+        title.downcase.gsub(' ', '-').gsub('(', '').gsub(')', '')
+      end
+
+      # Generates a hash with the attributes used in {govuk_step_by_step_navigation}
+      #
+      # @param govuk_step_by_step_navigation_options [Hash] options that will be used in customising the HTML
+      #
+      # @option (see govuk_step_by_step_navigation)
+      #
+      # @return [Hash] contains the HTMl attributes used in {govuk_step_by_step_navigation}
+
+      def govuk_step_by_step_navigation_attributes(**govuk_step_by_step_navigation_options)
+        govuk_step_by_step_navigation_options[:attributes] ||= {}
+        (govuk_step_by_step_navigation_options[:attributes][:data] ||= {}).merge!({ module: 'govuk-step-by-step-navigation' })
+
+        DEFAULT_SHOW_HIDE_TEXT.each { |key, value| govuk_step_by_step_navigation_options[:attributes][:data][key] ||= value }
+
+        govuk_step_by_step_navigation_options[:attributes]
+      end
+
+      # Default text for the show and hide buttons which are part of each section
+
+      DEFAULT_SHOW_HIDE_TEXT = { 'show-text': 'Show', 'hide-text': 'Hide', 'show-all-text': 'Show all', 'hide-all-text': 'Hide all' }.freeze
+    end
+  end
+end