ccs-frontend_helpers 0.1.0.rc.1

data/lib/ccs/frontend_helpers/govuk_frontend/breadcrumbs.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+require_relative '../shared_methods'
+
+module CCS
+  module FrontendHelpers
+    module GovUKFrontend
+      # = GOV.UK Breadcrumbs
+      #
+      # This helper is used for generating the breadcrumbs component from the
+      # {https://design-system.service.gov.uk/components/breadcrumbs GDS - Components - Breadcrumbs}
+
+      module Breadcrumbs
+        include SharedMethods
+        include ActionView::Context
+        include ActionView::Helpers::TagHelper
+        include ActionView::Helpers::TextHelper
+        include ActionView::Helpers::UrlHelper
+
+        # Generates the HTML for the GOV.UK breadcrumbs component
+        #
+        # @param govuk_breadcrumb_items [Array<Hash>] An array of links for the breadcrumbs list. See {#govuk_breadcrumb_link} for details of the items in the array.
+        # @param govuk_breadcrumbs_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_breadcrumbs_options [String] :classes additional CSS classes for the breadcrumbs HTML
+        # @option govuk_breadcrumbs_options [Boolean] :collapse_on_mobile indicates if it is to colapse breadcrumbs on mobile
+        # @option govuk_breadcrumbs_options [Hash] :attributes any additional attributes that will added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Breadcrumbs
+        #                                     which can then be rendered on the page
+
+        def govuk_breadcrumbs(govuk_breadcrumb_items, **govuk_breadcrumbs_options)
+          initialise_attributes_and_set_classes(govuk_breadcrumbs_options, 'govuk-breadcrumbs')
+
+          govuk_breadcrumbs_options[:attributes][:class] << ' govuk-breadcrumbs--collapse-on-mobile' if govuk_breadcrumbs_options[:collapse_on_mobile]
+
+          tag.div(**govuk_breadcrumbs_options[:attributes]) do
+            tag.ol(class: 'govuk-breadcrumbs__list') do
+              govuk_breadcrumb_items.each { |govuk_breadcrumb_item| concat(govuk_breadcrumb_link(govuk_breadcrumb_item)) }
+            end
+          end
+        end
+
+        private
+
+        # Generates the HTML for each link in the breadcrumbs.
+        # It is called by {#govuk_breadcrumbs} which will pass in the breadcrum item.
+        #
+        # @param govuk_breadcrumb_item [Hash] a hash containg options for the breadcrumb item
+        #
+        # @option govuk_breadcrumb_item [String] :text the text for the link
+        # @option govuk_breadcrumb_item [String] :href the URI for the link. If blank it is assumed that this item relates to current page
+        # @option govuk_breadcrumb_item [Hash] :attributes any additional attributes that will added as part of the HTML.
+        #                                                  If the link is blank then it defaults to +{ aria: { current: 'page' } }+
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Breadcrumb list item
+
+        def govuk_breadcrumb_link(govuk_breadcrumb_item)
+          if govuk_breadcrumb_item[:href].present?
+            (govuk_breadcrumb_item[:attributes] ||= {})[:class] = 'govuk-breadcrumbs__link'
+
+            tag.li(class: 'govuk-breadcrumbs__list-item') do
+              link_to(govuk_breadcrumb_item[:text], govuk_breadcrumb_item[:href], **govuk_breadcrumb_item[:attributes])
+            end
+          else
+            tag.li(class: 'govuk-breadcrumbs__list-item', aria: { current: 'page' }) do
+              govuk_breadcrumb_item[:text]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ccs/frontend_helpers/govuk_frontend/button.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+require_relative '../shared_methods'
+
+module CCS
+  module FrontendHelpers
+    module GovUKFrontend
+      # = GOV.UK Button
+      #
+      # This helper is used for generating the button component from the
+      # {https://design-system.service.gov.uk/components/button GDS - Components - Button}
+
+      module Button
+        include SharedMethods
+        include ActionView::Context
+        include ActionView::Helpers::TagHelper
+        include ActionView::Helpers::TextHelper
+        include ActionView::Helpers::UrlHelper
+        include ActionView::Helpers::FormTagHelper
+
+        # Generates the HTML for the GOV.UK button component
+        #
+        # @param text [String] the text that will be shown in the button
+        # @param govuk_button_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_button_options [String] :classes additional CSS classes for the button HTML
+        # @option govuk_button_options [Boolean] :is_start_button indicates if it is a start button
+        # @option govuk_button_options [String] :href the URI that will be used in anchor tag
+        # @option govuk_button_options [ActionView::Helpers::FormBuilder] :form the form builder used to create the submit button
+        # @option govuk_button_options [Hash] :attributes ({ data: { module: 'govuk-button' } }) any additional attributes that will added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Button
+        #                                     which can then be rendered on the page
+
+        def govuk_button(text, **govuk_button_options)
+          initialise_attributes_and_set_classes(govuk_button_options, 'govuk-button')
+          set_data_module(govuk_button_options, 'govuk-button')
+
+          govuk_button_options[:attributes][:class] << ' govuk-button--disabled' if govuk_button_options[:attributes][:disabled]
+          govuk_button_options[:attributes][:class] << ' govuk-button--start' if govuk_button_options[:is_start_button]
+
+          button_method = if govuk_button_options[:href]
+                            :govuk_button_link
+                          elsif govuk_button_options[:form]
+                            :govuk_button_submit
+                          else
+                            :govuk_button_button
+                          end
+
+          send(button_method, text, **govuk_button_options)
+        end
+
+        private
+
+        # Generates the HTML for the GOV.UK button component as an anchor tag.
+        # It is called by {#govuk_button} which will pass in the parameters, including any defaults.
+        #
+        # @param text [String] the text that will be shown in the button
+        # @param govuk_button_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_button_options [Boolean] :is_start_button indicates if it is a start button
+        # @option govuk_button_options [String] :href the URI that will be used in anchor tag
+        # @option govuk_button_options [Hash] :attributes any additional attributes that will added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Button as an anchor element
+        #                                     which can then be rendered on the page
+
+        def govuk_button_link(text, **govuk_button_options)
+          govuk_button_options[:attributes][:role] = :button
+          govuk_button_options[:attributes][:draggable] = false
+
+          link_to(govuk_button_options[:href], **govuk_button_options[:attributes]) do
+            concat(text)
+            concat(govuk_start_button_icon) if govuk_button_options[:is_start_button]
+          end
+        end
+
+        # Generates the HTML for the GOV.UK button component as a button.
+        # It is called by {#govuk_button} which will pass in the parameters, including any defaults.
+        #
+        # @param text [String] the text that will be shown in the button
+        # @param govuk_button_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_button_options [Boolean] :is_start_button indicates if it is a start button
+        # @option govuk_button_options [Hash] :attributes any additional attributes that will added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Button as a button element
+        #                                     which can then be rendered on the page
+
+        def govuk_button_button(text, **govuk_button_options)
+          button_tag(**govuk_button_options[:attributes]) do
+            concat(text)
+            concat(govuk_start_button_icon) if govuk_button_options[:is_start_button]
+          end
+        end
+
+        # Generates the HTML for the GOV.UK button component as an input.
+        # It is called by {#govuk_button} which will pass in the parameters, including any defaults.
+        #
+        # @param text [String] the text that will be shown in the input
+        # @param govuk_button_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_button_options [ActionView::Helpers::FormBuilder] :form the form builder used to create the submit button
+        # @option govuk_button_options [Hash] :attributes any additional attributes that will added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Button as an input element
+        #                                     which can then be rendered on the page
+
+        def govuk_button_submit(text, **govuk_button_options)
+          govuk_button_options[:form].submit(text, **govuk_button_options[:attributes])
+        end
+
+        # Generates the arrow for the start button option as part of {#govuk_button}
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the arrow for the start button
+
+        def govuk_start_button_icon
+          tag.svg(class: 'govuk-button__start-icon', xmlns: 'http://www.w3.org/2000/svg', width: 17.5, height: 19, viewBox: '0 0 33 40', aria: { hidden: true }, focusable: false) do
+            tag.path(fill: 'currentColor', d: 'M0 0h13l20 20-20 20H0l20-20z')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ccs/frontend_helpers/govuk_frontend/cookie_banner.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative 'button'
+
+module CCS
+  module FrontendHelpers
+    module GovUKFrontend
+      # = GOV.UK Cookie Banner
+      #
+      # This helper is used for generating the cookie banner component from the
+      # {https://design-system.service.gov.uk/components/cookie-banner GDS - Components - Cookie banner}
+
+      module CookieBanner
+        include ActionView::Context
+        include ActionView::Helpers::TagHelper
+        include ActionView::Helpers::TextHelper
+        include Button
+
+        # Generates the HTML for the GOV.UK Cookie banner component
+        #
+        # @param messages [Array] the different messages you can pass into the cookie banner. See {govuk_cookie_banner_message_content}
+        # @param govuk_cookie_banner_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_cookie_banner_options [String] :classes additional CSS classes for the cookie banner HTML
+        # @option govuk_cookie_banner_options [Hash] :attributes any additional attributes that will added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Cookie banner
+        #                                     which can then be rendered on the page
+
+        def govuk_cookie_banner(messages, **govuk_cookie_banner_options)
+          determine_govuk_cookie_banner_attributes(govuk_cookie_banner_options)
+
+          tag.div(**govuk_cookie_banner_options[:attributes]) do
+            messages.each do |message|
+              initialise_attributes_and_set_classes(message, 'govuk-cookie-banner__message govuk-width-container')
+
+              concat(tag.div(**message[:attributes]) do
+                concat(govuk_cookie_banner_message_content(message))
+                concat(govuk_cookie_banner_message_actions(message[:actions])) if message[:actions]
+              end)
+            end
+          end
+        end
+
+        private
+
+        # Generates the HTML for a cookie banner message content used in {govuk_cookie_banner}
+        #
+        # @param message [Hash] the options for the cookie banner message
+        #
+        # @option message [String] :heading_text the heading text that displays in the message
+        # @option message [ActiveSupport::SafeBuffer] :content HTML to use as content for the message
+        # @option message [String] :text if +:content+ is blank then this is the text used for the message
+        # @option message [Array] :actions the buttons and links that you want to display in the message. See {govuk_cookie_banner_message_actions}
+        # @option message [String] :classes additional CSS classes for the cookie message HTML
+        # @option message [Hash] :attributes any additional attributes that will added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for a cookie banner message content used in {govuk_cookie_banner}
+
+        def govuk_cookie_banner_message_content(message)
+          tag.div(class: 'govuk-grid-row') do
+            tag.div(class: 'govuk-grid-column-two-thirds') do
+              concat(tag.h2(message[:heading_text], class: 'govuk-cookie-banner__heading govuk-heading-m')) if message[:heading_text]
+              concat(tag.div(class: 'govuk-cookie-banner__content') do
+                message[:content] || tag.p(message[:text], class: 'govuk-body')
+              end)
+            end
+          end
+        end
+
+        # rubocop:disable Metrics/AbcSize
+
+        # Generates the HTML for the cookie banner message actions used in {govuk_cookie_banner}
+        # It defaults to creating button unless a +href+ is set which will create a link
+        #
+        # @param message_actions [Hash] the options for the cookie banner message actions
+        #
+        # @option message_actions [String] :text the button or link text
+        # @option message_actions [String] :href the href for a link
+        # @option message_actions [String] :classes additional CSS classes for the cookie action button or link
+        # @option message_actions [Hash] :attributes any additional attributes that will added as part of the HTML.
+        #                                            If the +:type+ key is present with a value of +:button+,
+        #                                            the action will be rendered as a button
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the cookie banner message actions used in {govuk_cookie_banner}
+
+        def govuk_cookie_banner_message_actions(message_actions)
+          tag.div(class: 'govuk-button-group') do
+            message_actions.each do |message_action|
+              message_action[:attributes] ||= {}
+
+              concat(
+                if message_action[:href]
+                  if message_action[:attributes][:type] == :button
+                    govuk_button(
+                      message_action[:text],
+                      href: message_action[:href],
+                      classes: message_action[:classes],
+                      attributes: message_action[:attributes]
+                    )
+                  else
+                    message_action[:attributes][:class] = "govuk-link #{message_action[:classes]}".rstrip
+
+                    link_to(message_action[:text], message_action[:href], **message_action[:attributes])
+                  end
+                else
+                  govuk_button(
+                    message_action[:text],
+                    classes: message_action[:classes],
+                    attributes: message_action[:attributes]
+                  )
+                end
+              )
+            end
+          end
+        end
+
+        # rubocop:enable Metrics/AbcSize
+
+        # Sets the default attributes for {govuk_cookie_banner}
+        #
+        # @param govuk_cookie_banner_options [Hash] options that will be used in customising the HTML
+        #
+        # @option (see govuk_cookie_banner)
+
+        def determine_govuk_cookie_banner_attributes(govuk_cookie_banner_options)
+          initialise_attributes_and_set_classes(govuk_cookie_banner_options, 'govuk-cookie-banner')
+
+          (govuk_cookie_banner_options[:attributes][:data] ||= {})[:nosnippet] = 'true'
+          govuk_cookie_banner_options[:attributes][:role] = 'region'
+          (govuk_cookie_banner_options[:attributes][:aria] ||= {})[:label] ||= 'Cookie banner'
+        end
+      end
+    end
+  end
+end

data/lib/ccs/frontend_helpers/govuk_frontend/details.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+require_relative '../shared_methods'
+
+module CCS
+  module FrontendHelpers
+    module GovUKFrontend
+      # = GOV.UK Details
+      #
+      # This helper is used for generating the details component from the
+      # {https://design-system.service.gov.uk/components/details GDS - Components - Details}
+
+      module Details
+        include SharedMethods
+        include ActionView::Context
+        include ActionView::Helpers::TagHelper
+        include ActionView::Helpers::TextHelper
+
+        # Generates the HTML for the GOV.UK Details component
+        #
+        # @param summary_text [String] the summary text for the details element
+        # @param govuk_details_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_details_options [String] :classes additional CSS classes for the details HTML
+        # @option govuk_details_options [Hash] :attributes ({ data: { module: 'govuk-details' } }) any additional attributes that will added as part of the HTML
+        #
+        # @yield HTML that will be contained within the 'govuk-details__text' div
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Details
+        #                                     which can then be rendered on the page
+
+        def govuk_details(summary_text, **govuk_details_options, &block)
+          initialise_attributes_and_set_classes(govuk_details_options, 'govuk-details')
+          set_data_module(govuk_details_options, 'govuk-details')
+
+          tag.details(**govuk_details_options[:attributes]) do
+            concat(tag.summary(tag.span(summary_text, class: 'govuk-details__summary-text'), class: 'govuk-details__summary'))
+            concat(tag.div(class: 'govuk-details__text', &block))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ccs/frontend_helpers/govuk_frontend/error_message.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+require_relative '../shared_methods'
+
+module CCS
+  module FrontendHelpers
+    module GovUKFrontend
+      # = GOV.UK Error Message
+      #
+      # This helper is used for generating the error message component from the
+      # {https://design-system.service.gov.uk/components/error-message GDS - Components - Error message}
+
+      module ErrorMessage
+        include SharedMethods
+        include ActionView::Context
+        include ActionView::Helpers::TagHelper
+        include ActionView::Helpers::TextHelper
+
+        # Generates the HTML for the GOV.UK Error message component
+        #
+        # @param message [String] the message to be displayed
+        # @param attribute [String, Symbol] the attribute that has an error
+        # @param govuk_error_message_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_error_message_options [String] :classes additional CSS classes for the error message HTML
+        # @option govuk_error_message_options [String] :visually_hidden_text ('Error') visualy hidden text before the error message
+        # @option govuk_error_message_options [Hash] :attributes ({}) any additional attributes that will be added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Error message
+        #                                     which can then be rendered on the page
+
+        def govuk_error_message(message, attribute, **govuk_error_message_options)
+          initialise_attributes_and_set_classes(govuk_error_message_options, 'govuk-error-message')
+
+          govuk_error_message_options[:attributes][:id] ||= "#{attribute}-error"
+          visually_hidden_text = govuk_error_message_options[:visually_hidden_text] || 'Error'
+
+          tag.p(**govuk_error_message_options[:attributes]) do
+            concat(tag.span("#{visually_hidden_text}: ", class: 'govuk-visually-hidden')) if visually_hidden_text.present?
+            concat(message)
+          end
+        end
+
+        # Generates the HTML for the GOV.UK Error message component using the error messages in an ActiveModel
+        #
+        # @param model [ActiveModel] model that will be used to find the error message
+        # @param attribute [String, Symbol] the attribute that has an error
+        # @param govuk_error_message_options [Hash] options that will be used in customising the HTML
+        #
+        # @option (see #govuk_error_message)
+        #
+        # @return [NilClass, ActiveSupport::SafeBuffer] if the error message is not on the model it will return nil,
+        #                                               otherwise the HTML for the GOV.UK Error message
+        #                                               which can then be rendered on the page is returned
+
+        def govuk_error_message_with_model(model, attribute, **govuk_error_message_options)
+          error_message = model.errors[attribute].first
+          return unless error_message
+
+          govuk_error_message(error_message, attribute, **govuk_error_message_options)
+        end
+      end
+    end
+  end
+end

data/lib/ccs/frontend_helpers/govuk_frontend/error_summary.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+require_relative '../shared_methods'
+
+module CCS
+  module FrontendHelpers
+    module GovUKFrontend
+      # = GOV.UK Error Summary
+      #
+      # This helper is used for generating the error summary component from the
+      # {https://design-system.service.gov.uk/components/error-summary GDS - Components - Error summary}
+
+      module ErrorSummary
+        include SharedMethods
+        include ActionView::Context
+        include ActionView::Helpers::TagHelper
+        include ActionView::Helpers::TextHelper
+        include ActionView::Helpers::UrlHelper
+
+        # Generates the HTML for the GOV.UK Error summary component
+        #
+        # @param title [String] text to use for the heading of the error summary block
+        # @param error_list [Array] the list of errors to include in the summary. See {govuk_error_summary_list}
+        # @param description [String] optional text to use for the description of the errors
+        # @param govuk_error_summary_options [Hash] options that will be used in customising the HTML
+        #
+        # @option govuk_error_summary_options [String] :classes additional CSS classes for the error summary HTML
+        # @option govuk_error_summary_options [Hash] :attributes ({}) any additional attributes that will be added as part of the HTML
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the GOV.UK Error summary
+        #                                     which can then be rendered on the page
+
+        def govuk_error_summary(title, error_list, description = nil, **govuk_error_summary_options)
+          initialise_attributes_and_set_classes(govuk_error_summary_options, 'govuk-error-summary')
+          set_data_module(govuk_error_summary_options, 'govuk-error-summary')
+
+          tag.div(**govuk_error_summary_options[:attributes]) do
+            tag.div(role: 'alert') do
+              concat(tag.h2(title, class: 'govuk-error-summary__title'))
+              concat(tag.div(class: 'govuk-error-summary__body') do
+                concat(tag.p(description)) if description
+                concat(govuk_error_summary_list(error_list))
+              end)
+            end
+          end
+        end
+
+        # Generates the HTML for the GOV.UK Error summary component using the error messages in an ActiveModel
+        #
+        # @param model [ActiveModel] model that will be used to find the error messages to list
+        # @param title [String] text to use for the heading of the error summary block
+        # @param description [String] (nil) optional text to use for the description of the errors
+        # @param govuk_error_summary_options [Hash] options that will be used in customising the HTML
+        #
+        # @option (see #govuk_error_summary)
+        #
+        # @return [NilClass, ActiveSupport::SafeBuffer] if there are no errors on the model it will return nil,
+        #                                               otherwise the HTML for the GOV.UK Error summary
+        #                                               which can then be rendered on the page is returned
+
+        def govuk_error_summary_with_model(model, title, description = nil, **govuk_error_summary_options)
+          return if model.errors.blank?
+
+          error_list = model.errors.map { |error| { text: error.message, href: "##{error.attribute}-error" } }
+
+          govuk_error_summary(title, error_list, description, **govuk_error_summary_options)
+        end
+
+        private
+
+        # Generates the HTML for the error list in {govuk_error_summary}
+        #
+        # @param error_list [Array] The list of errors to include in the summary. See {#govuk_error_summary_list}
+        #
+        # @option error_list [String] :href href for the error link item. If provided item will be a link
+        # @option error_list [String] :text Text for the error link item
+        # @option error_list [Hash] :attributes ({}) any additional attributes that will be added as part of the link item
+        #
+        # @return [ActiveSupport::SafeBuffer] the HTML for the error list
+        #                                     which is used in {govuk_error_summary}
+
+        def govuk_error_summary_list(error_list)
+          tag.ul(class: 'govuk-list govuk-error-summary__list') do
+            error_list.each do |error|
+              concat(tag.li do
+                if error[:href]
+                  link_to(error[:text], error[:href], **(error[:attributes] || {}))
+                else
+                  error[:text]
+                end
+              end)
+            end
+          end
+        end
+      end
+    end
+  end
+end