katalyst-govuk-formbuilder 1.30.0 → 2.0.0

data/app/helpers/katalyst/govuk/form_builder/elements/attachment.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Elements
+        class Attachment < GOVUKDesignSystemFormBuilder::Elements::File
+          include FormBuilder::Traits::Attachment
+
+          def initialize(builder, object_name, attribute_name, direct_upload_url:,
+                         upload_succeeded_text: nil, upload_failed_text: nil,
+                         retry_button_text: nil, file_removed_text: nil,
+                         remove_button_text: nil, remove_button_content_text: nil, **, &)
+            super(builder, object_name, attribute_name, javascript: true, **, &)
+
+            @direct_upload_url          = direct_upload_url
+            @upload_succeeded_text      = upload_succeeded_text
+            @upload_failed_text         = upload_failed_text
+            @retry_button_text          = retry_button_text
+            @file_removed_text          = file_removed_text
+            @remove_button_text         = remove_button_text
+            @remove_button_content_text = remove_button_content_text
+
+            raise ArgumentError, "Unsupported attribute type #{value.class} for #{attribute_name}" unless attachment?
+          end
+
+          def options
+            super.merge(
+              "data-direct-upload-url" => @direct_upload_url,
+              include_hidden: false, # we always render remove_field
+              multiple: many?,
+            )
+          end
+
+          private
+
+          # Extends the file element's data-i18n.* attributes with the
+          # attachment strings: an explicit option wins, else the current
+          # locale's translation. When neither adds anything beyond the
+          # gem's en defaults the attribute is omitted and the JS falls
+          # back to its bundled mirror of the same table.
+          def i18n_data
+            super.merge({
+              "data-i18n.upload-succeeded"      => attachment_text(@upload_succeeded_text, :upload_succeeded),
+              "data-i18n.upload-failed"         => attachment_text(@upload_failed_text, :upload_failed),
+              "data-i18n.retry-button"          => attachment_text(@retry_button_text, :retry_button),
+              "data-i18n.file-removed"          => attachment_text(@file_removed_text, :file_removed),
+              "data-i18n.remove-button"         => attachment_text(@remove_button_text, :remove_button),
+              "data-i18n.remove-button-content" => attachment_text(@remove_button_content_text, :remove_button_content),
+            }.compact)
+          end
+
+          def attachment_text(option, key)
+            return option if option
+
+            text = attachment_translation(key)
+            text unless text == Traits::Attachment::BUNDLED_DEFAULTS[key.to_s]
+          end
+
+          def file
+            safe_join([remove_field, attachment, @builder.file_field(@attribute_name, attributes(@html_attributes))])
+          end
+
+          def file_with_javascript_markup
+            tag.div(class: "#{brand}-file-upload-wrapper", data: { controller: "govuk-file-upload" }, **i18n_data) do
+              file
+            end
+          end
+
+          # A removed figure takes its select with it and an empty file input contributes
+          # no value. This input ensures that there's always a value to process so that
+          # attachments can be removed (both one? and many? cases).
+          def remove_field
+            tag.input(name: @builder.field_name(@attribute_name, multiple: many?), type: "hidden", value: "")
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/govuk/form_builder/elements/combobox.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "govuk_design_system_formbuilder"
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Elements
+        class Combobox < GOVUKDesignSystemFormBuilder::Base
+          include GOVUKDesignSystemFormBuilder::Traits::Error
+          include GOVUKDesignSystemFormBuilder::Traits::Label
+          include GOVUKDesignSystemFormBuilder::Traits::Hint
+          include GOVUKDesignSystemFormBuilder::Traits::HTMLAttributes
+          include GOVUKDesignSystemFormBuilder::Traits::ContentBeforeAndAfter
+
+          def initialize(builder,
+                         object_name,
+                         attribute_name,
+                         options_or_src,
+                         options:,
+                         form_group:,
+                         label:,
+                         hint:,
+                         caption:,
+                         before_input:,
+                         after_input:,
+                         **kwargs,
+                         &block)
+            # assign the block to a variable rather than passing to super so
+            # we can send it through to #combobox
+            super(builder, object_name, attribute_name)
+            @block           = block
+
+            @form_group      = form_group
+            @hint            = hint
+            @label           = label
+            @caption         = caption
+            @options_or_src  = options_or_src
+            @options         = options
+            @html_attributes = kwargs
+            @before_input    = before_input
+            @after_input     = after_input
+          end
+
+          def html
+            GOVUKDesignSystemFormBuilder::Containers::FormGroup.new(*bound, **@form_group).html do
+              safe_join([
+                          label_element,
+                          hint_element,
+                          error_element,
+                          before_input_content,
+                          combobox,
+                          after_input_content,
+                        ])
+            end
+          end
+
+          private
+
+          def combobox
+            attrs         = attributes(@html_attributes)
+            attrs[:class] = attrs.delete(:class).join(" ") # hotwire_combobox does not support flattening classes
+            @builder.combobox(@attribute_name, @options_or_src, **@options, **attrs, &@block)
+          end
+
+          def options
+            {
+              id:    field_id(link_errors: true),
+              class: classes,
+              aria:  { describedby: combine_references(hint_id, error_id) },
+            }
+          end
+
+          def classes
+            combine_references(%(#{brand}-combobox), error_class)
+          end
+
+          def error_class
+            %(#{brand}-combobox--error) if has_errors?
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/govuk/form_builder/elements/document.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "govuk_design_system_formbuilder"
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Elements
+        class Document < GOVUKDesignSystemFormBuilder::Base
+          include ActionDispatch::Routing::RouteSet::MountedHelpers
+
+          include GOVUKDesignSystemFormBuilder::Traits::Error
+          include GOVUKDesignSystemFormBuilder::Traits::Hint
+          include GOVUKDesignSystemFormBuilder::Traits::Label
+          include GOVUKDesignSystemFormBuilder::Traits::Supplemental
+          include GOVUKDesignSystemFormBuilder::Traits::HTMLAttributes
+          include GOVUKDesignSystemFormBuilder::Traits::HTMLClasses
+
+          include FormBuilder::Traits::File
+
+          def initialize(builder, object_name, attribute_name, hint:, label:, caption:, form_group:, mime_types:,
+                         **kwargs, &)
+            super(builder, object_name, attribute_name, &)
+
+            @mime_types      = mime_types
+            @label           = label
+            @caption         = caption
+            @hint            = hint
+            @html_attributes = kwargs.merge(file_input_options)
+            @form_group      = form_group
+          end
+
+          def html
+            GOVUKDesignSystemFormBuilder::Containers::FormGroup.new(
+              *bound,
+              **default_form_group_options(**@form_group),
+            ).html do
+              safe_join([label_element, preview, hint_element, error_element, file, destroy_element,
+                         supplemental_content])
+            end
+          end
+
+          def preview
+            options          = {}
+            add_option(options, :data, "#{stimulus_controller}_target", "preview")
+            add_option(options, :class, "preview-file")
+            options[:hidden] = "" unless preview?
+
+            tag.div(**options) do
+              filename = @builder.object.send(@attribute_name).filename.to_s
+              tag.p(filename, class: "preview-filename") + destroy_element_trigger
+            end
+          end
+
+          private
+
+          def stimulus_controller
+            "govuk-document-field"
+          end
+
+          def form_group_class
+            "govuk-document-field"
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/govuk/form_builder/elements/image.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Elements
+        class Image < GOVUKDesignSystemFormBuilder::Base
+          include ActionDispatch::Routing::RouteSet::MountedHelpers
+
+          include GOVUKDesignSystemFormBuilder::Traits::Error
+          include GOVUKDesignSystemFormBuilder::Traits::Hint
+          include GOVUKDesignSystemFormBuilder::Traits::Label
+          include GOVUKDesignSystemFormBuilder::Traits::Supplemental
+          include GOVUKDesignSystemFormBuilder::Traits::HTMLAttributes
+          include GOVUKDesignSystemFormBuilder::Traits::HTMLClasses
+
+          include FormBuilder::Traits::File
+
+          def initialize(builder, object_name, attribute_name, hint:, label:, caption:, form_group:, mime_types:,
+                         **kwargs, &)
+            super(builder, object_name, attribute_name, &)
+
+            @mime_types      = mime_types
+            @label           = label
+            @caption         = caption
+            @hint            = hint
+            @html_attributes = kwargs.merge(file_input_options)
+            @form_group      = form_group
+          end
+
+          def html
+            GOVUKDesignSystemFormBuilder::Containers::FormGroup.new(
+              *bound,
+              **default_form_group_options(**@form_group),
+            ).html do
+              safe_join([label_element, preview, hint_element, error_element, file, destroy_element,
+                         supplemental_content])
+            end
+          end
+
+          def preview
+            options          = {}
+            add_option(options, :data, "#{stimulus_controller}_target", "preview")
+            add_option(options, :class, "preview-image")
+            options[:hidden] = "" unless preview?
+
+            tag.div(**options) do
+              tag.img(src: preview_url, class: "image-thumbnail") + destroy_element_trigger
+            end
+          end
+
+          private
+
+          def stimulus_controller
+            "govuk-image-field"
+          end
+
+          def form_group_class
+            "govuk-image-field"
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/govuk/form_builder/elements/label.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "govuk_design_system_formbuilder"
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Elements
+        # Extend Elements::Label to add support for human_attribute_name as a fallback
+        module Label
+          extend ActiveSupport::Concern
+
+          included do
+            def retrieve_text(option_text, hidden)
+              text = option_text.presence ||
+                localised_text(:label).presence ||
+                human_attribute_name.presence ||
+                @attribute_name.to_s.humanize.capitalize.presence
+
+              if hidden
+                tag.span(text, class: %(#{brand}-visually-hidden))
+              else
+                text
+              end
+            end
+          end
+
+          def human_attribute_name
+            return unless @object_name.present? && @attribute_name.present?
+            return unless @builder.object&.class.respond_to?(:human_attribute_name)
+
+            @builder.object.class.human_attribute_name(@attribute_name)
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/govuk/form_builder/elements/legend.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "govuk_design_system_formbuilder"
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Elements
+        # Extend Elements::Legend to add support for human_attribute_name as a fallback
+        module Legend
+          extend ActiveSupport::Concern
+
+          included do
+            def retrieve_text(supplied_text)
+              supplied_text.presence ||
+                localised_text(:legend).presence ||
+                human_attribute_name.presence ||
+                @attribute_name.to_s.humanize.capitalize.presence
+            end
+          end
+
+          def human_attribute_name
+            return unless @object_name.present? && @attribute_name.present?
+            return unless @builder.object&.class.respond_to?(:human_attribute_name)
+
+            @builder.object.class.human_attribute_name(@attribute_name)
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/govuk/form_builder/elements/rich_textarea.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "govuk_design_system_formbuilder"
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Elements
+        class RichTextarea < GOVUKDesignSystemFormBuilder::Base
+          using GOVUKDesignSystemFormBuilder::PrefixableArray
+
+          include GOVUKDesignSystemFormBuilder::Traits::Error
+          include GOVUKDesignSystemFormBuilder::Traits::Hint
+          include GOVUKDesignSystemFormBuilder::Traits::Label
+          include GOVUKDesignSystemFormBuilder::Traits::Supplemental
+          include GOVUKDesignSystemFormBuilder::Traits::HTMLAttributes
+          include GOVUKDesignSystemFormBuilder::Traits::HTMLClasses
+
+          def initialize(
+            builder,
+            object_name,
+            attribute_name,
+            hint:,
+            label:,
+            caption:,
+            form_group:,
+            **kwargs,
+            &
+          )
+            super(builder, object_name, attribute_name, &)
+
+            @label           = label
+            @caption         = caption
+            @hint            = hint
+            @form_group      = form_group
+            @html_attributes = kwargs
+          end
+
+          def html
+            GOVUKDesignSystemFormBuilder::Containers::FormGroup.new(*bound, **@form_group).html do
+              safe_join([label_element, supplemental_content, hint_element, error_element, rich_textarea])
+            end
+          end
+
+          private
+
+          def rich_textarea
+            @builder.rich_textarea(@attribute_name, **attributes(@html_attributes))
+          end
+
+          def classes
+            build_classes(%(rich-textarea), %(rich-textarea--error) => has_errors?).prefix(brand)
+          end
+
+          def options
+            {
+              id:    field_id,
+              class: classes,
+              aria:  { describedby: combine_references(hint_id, error_id) },
+            }
+          end
+
+          def label_content
+            super.merge(link_errors: false)
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/govuk/form_builder/frontend.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Frontend
+        # Marks the page as JS-capable and enhances govuk-frontend components,
+        # on load and as the DOM changes (Turbo morphs, lazily-loaded frames,
+        # stream inserts). Render at the end of <body>; on a Turbo replace
+        # render the snippet re-executes with the new body, and everything it
+        # sets up is scoped to the body element it ran against.
+        # rubocop:disable Rails/OutputSafety
+        def govuk_formbuilder_init
+          tag.script type: "module", nonce: request.content_security_policy_nonce do
+            <<~JS.html_safe
+              import {initAll} from "@katalyst/govuk-formbuilder";
+              initAll(#{govuk_formbuilder_init_options});
+            JS
+          end
+        end
+        # rubocop:enable Rails/OutputSafety
+
+        private
+
+        # The bundle's own default is govuk; only a non-default brand renders.
+        def govuk_formbuilder_init_options
+          brand = GOVUKDesignSystemFormBuilder.brand
+
+          brand.to_s == "govuk" ? "" : "{brand: #{brand.to_json}}"
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/govuk/form_builder/traits/attachment.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "govuk_design_system_formbuilder"
+
+module Katalyst
+  module GOVUK
+    module FormBuilder
+      module Traits
+        # Generates attachment inputs and previews for ActiveStorage associations.
+        module Attachment
+          extend ActiveSupport::Concern
+
+          include ActionView::Helpers::NumberHelper
+
+          # The attachment strings' canonical home (config/locales).
+          I18N_SCOPE = %i[katalyst govuk attachment].freeze
+
+          # The gem's own en strings, read straight from its locale file:
+          # resolving them through I18n would absorb a host app's en
+          # overrides, and this table is the baseline those overrides are
+          # detected against.
+          BUNDLED_DEFAULTS = YAML.load_file(
+            Engine.root.join("config/locales/en.yml"),
+          ).dig("en", *I18N_SCOPE.map(&:to_s)).freeze
+
+          def attachment?
+            value.is_a?(ActiveStorage::Attached)
+          end
+
+          def one?
+            value.is_a?(ActiveStorage::Attached::One)
+          end
+
+          def many?
+            value.is_a?(ActiveStorage::Attached::Many)
+          end
+
+          def value
+            @builder.object.send(@attribute_name)
+          end
+
+          delegate :attached?, to: :value
+
+          # @return [ActiveSupport::SafeBuffer,nil]
+          def attachment
+            return unless attached?
+
+            # Preserve unsaved multi-part form uploads before rendering
+            # mimics direct-upload for non-js consumers.
+            persist_pending_blobs
+
+            blobs = (one? ? [value.blob] : value.blobs).select(&:persisted?)
+            safe_join(blobs.map { |blob| attachment_for(blob) })
+          end
+
+          # @param [ActiveStorage::Blob] blob
+          # @return [ActiveSupport::SafeBuffer,nil]
+          def attachment_for(blob)
+            tag.figure(class: "#{brand}-attachment",
+                       aria:  { labelledby: attachment_id_for(blob, :filename) },
+                       data:  { controller: "govuk-attachment" }) do
+              safe_join([
+                          attachment_preview_for(blob),
+                          attachment_caption_for(blob),
+                          attachment_actions_for(blob),
+                        ])
+            end
+          end
+
+          # A <div> with form elements for managing the attachment.
+          # @param [ActiveStorage::Blob] blob
+          # @return [ActiveSupport::SafeBuffer|nil]
+          def attachment_actions_for(blob)
+            return if blob.nil?
+
+            tag.div(class: "actions") do
+              safe_join([
+                          attachment_input_for(blob),
+                          attachment_remove_for(blob),
+                        ])
+            end
+          end
+
+          # A <select> with options to keep or remove the attachment that can be used without JavaScript.
+          # @param [ActiveStorage::Blob] blob
+          # @return [ActiveSupport::SafeBuffer,nil]
+          def attachment_input_for(blob)
+            @builder.select(
+              @attribute_name,
+              [[blob.filename.to_s, blob.signed_id],
+               [remove_button_label(blob), ""]],
+              { selected: blob.signed_id },
+              id:   attachment_id_for(blob, :input),
+              name: @builder.field_name(@attribute_name, multiple: many?),
+              aria: { labelledby: attachment_id_for(blob, :filename) },
+            )
+          end
+
+          # A <button> that will remove the attachment when clicked (requires javascript).
+          # @param [ActiveStorage::Blob] blob
+          # @return [ActiveSupport::SafeBuffer,nil]
+          def attachment_remove_for(blob)
+            tag.button(remove_button_content,
+                       type:  "button",
+                       class: "#{brand}-button #{brand}-button--secondary #{brand}-attachment__remove",
+                       aria:  { label: remove_button_label(blob) },
+                       data:  { action: "govuk-attachment#destroy", module: "govuk-button" })
+          end
+
+          # The remove strings render here and in the JS figure template, so
+          # both draw from the same options (or matching defaults) — the two
+          # figure sources must stay string-identical.
+          # @param [ActiveStorage::Blob] blob
+          # @return [String]
+          def remove_button_label(blob)
+            if @remove_button_text
+              # %{filename} is the option placeholder (govuk-frontend's i18n
+              # convention), substituted directly — not a Ruby format token.
+              # rubocop:disable Style/FormatStringToken
+              @remove_button_text.gsub("%{filename}", blob.filename.to_s)
+              # rubocop:enable Style/FormatStringToken
+            else
+              attachment_translation(:remove_button, filename: blob.filename.to_s)
+            end
+          end
+
+          # @return [String]
+          def remove_button_content
+            @remove_button_content_text || attachment_translation(:remove_button_content)
+          end
+
+          # The current locale's translation, falling back to the gem's en
+          # defaults rather than a "translation missing" marker.
+          # @return [String]
+          def attachment_translation(key, **)
+            I18n.t(key, scope: I18N_SCOPE, default: nil, **) ||
+              I18n.t(key, scope: I18N_SCOPE, locale: :en, **)
+          end
+
+          # The representation is rendered lazily: the variant is processed
+          # when the browser requests it, never during the form render. If the
+          # blob's bytes turn out to be missing or unprocessable the preview
+          # simply fails to load — validating attachment content is the
+          # model's responsibility, not the form's.
+          # @param [ActiveStorage::Blob] blob
+          # @return [ActiveSupport::SafeBuffer,nil]
+          def attachment_preview_for(blob)
+            return unless blob.representable?
+
+            url = @builder.attachment_preview_url(
+              blob.representation(config.attachment_preview_representation),
+            )
+            return if url.nil?
+
+            # Setting alt to "" as the details already describe the attachment, equivalent to role="presentation"
+            @builder.image_tag(url, alt: "", class: "preview")
+          end
+
+          # The caption is a polite atomic live region: JS writes upload status
+          # into the status span, and the announcement reads the whole caption
+          # so the user hears which file the status belongs to.
+          # @param [ActiveStorage::Blob] blob
+          # @return [ActiveSupport::SafeBuffer,nil]
+          def attachment_caption_for(blob)
+            tag.figcaption(class: "caption", aria: { atomic: true, live: "polite" }) do
+              safe_join([
+                          tag.span(blob.filename, id: attachment_id_for(blob, :filename), class: "filename"),
+                          " ",
+                          tag.span(number_to_human_size(blob.byte_size), class: "size"),
+                          " ",
+                          tag.span(class: "status"),
+                        ])
+            end
+          end
+
+          # @param [ActiveStorage::Blob] blob
+          # @return [String,nil]
+          def attachment_id_for(blob, *suffixes)
+            return nil if @html_attributes.fetch(:skip_default_ids, false)
+
+            @builder.field_id(@attribute_name, :attachment, blob.id, *suffixes)
+          end
+
+          private
+
+          def persist_pending_blobs
+            case (change = @builder.object.attachment_changes[@attribute_name.to_s])
+            when ActiveStorage::Attached::Changes::CreateOne
+              persist_pending_change(change)
+            when ActiveStorage::Attached::Changes::CreateMany
+              change.pending_uploads.each do |subchange|
+                persist_pending_change(subchange)
+              end
+            end
+          end
+
+          def persist_pending_change(change)
+            change.upload
+            change.blob.save!
+          rescue ActiveStorage::Error, Errno::ENOENT => e
+            # no recovery available (ENOENT: tempfile vanished before render)
+            log_dropped_upload(e)
+          end
+
+          def log_dropped_upload(error)
+            Rails.logger.warn(
+              "Dropped pending attachment for " \
+              "#{@builder.object.class}##{@attribute_name}: #{error.class}: #{error.message}",
+            )
+          end
+        end
+      end
+    end
+  end
+end