katalyst-govuk-formbuilder 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 205c71b26044c257f432d3ab429eff7beeeb0c924f775df314732703d240a04f
-  data.tar.gz: 9a1733f6a7e41eefdeb6c096f21cbe7a328d6d7a159b6c57b3382d3f6e153236
+  metadata.gz: 2d371dc77a725f4e009f3a0a61e75d085f3080bad8cb64857299a3a7264fb95e
+  data.tar.gz: 392fcc8460909ba2a4190352a15cdd536a5e5e6e3d3ce896ae874a56a5aebef6
 SHA512:
-  metadata.gz: 5ccc46b82e579a72033f4f79b5afd9f8928962cc67b4f19d4e0a8b513ded75b56c96af01e567e9456a1ab85c520c83da1a2854a27c961561f680e89be14b25f4
-  data.tar.gz: 6ed137133d42622545c5f3b9178f7165976a7eaf732f29bcd353ddcd10232bd84a20dc93488257cb9765a2b0713a05561702c69291efc38d1619633a45f211aa
+  metadata.gz: cefbeb3e8423be0a86e33b324f59a3745aab8fd7e8a150a9e0be5dc4f874378108253db1f722c68b67defc3d96606db4dcef6576684f895445463cd905bf7f43
+  data.tar.gz: 8d688517167cc77a120aa50ac7d5e101524e8478c381071d603f650e303cc17ed9b0ea802cb6be15859717a2555f30589868768e55f7848df5c4072cdec87c04

data/README.md

@@ -27,6 +27,12 @@ Add the stylesheet to your default layout:
 <%= stylesheet_link_tag "katalyst/govuk/formbuilder" %>
 ```
 
+You can also add it to your SASS build:
+
+```scss
+@use "katalyst/govuk/formbuilder";
+```
+
 Some GOVUK components require javascript enhancements 
 (see [GOVUK docs](https://frontend.design-system.service.gov.uk/get-started/#5-get-the-javascript-working)).
 
@@ -43,6 +49,30 @@ You'll need to include the helper to make this method available, which you can a
 helper Katalyst::GOVUK::Formbuilder::Frontend
 ```
 
+## Extensions
+
+We include some optional extensions for integrating with gems that we (Katalyst) commonly use.
+
+These require additional steps to use.
+
+### Hotwire Combobox
+
+[Hotwire Combobox](https://hotwirecombobox.com) is a promising option for adding asynchronous multi-select inputs to
+Rails forms. We're assuming importmaps and Turbo if this option is used.
+
+There's no explicit dependency so if you want to use this input you'll need to add:
+
+```
+gem "hotwire_combobox"
+```
+
+JS is added by the gem automatically (via importmaps), but you'll need to explicitly add CSS:
+
+```scss
+@use "katalyst/govuk/formbuilder";
+@use "katalyst/govuk/components/combobox";
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/katalyst/govuk-formbuilder.

data/app/assets/builds/katalyst/govuk/formbuilder.css

@@ -1365,7 +1365,7 @@
   border-radius: 0;
   color: #ffffff;
   background-color: #00703c;
-  box-shadow: 0 2px 0 #002d18;
+  box-shadow: 0 2px 0 rgb(0, 44.8, 24);
   text-align: center;
   vertical-align: top;
   cursor: pointer;
@@ -1407,7 +1407,7 @@
   border: 0;
 }
 .govuk-button:hover {
-  background-color: #005a30;
+  background-color: rgb(0, 89.6, 48);
 }
 .govuk-button:active {
   top: 2px;
@@ -1446,18 +1446,18 @@
 }
 .govuk-button[disabled]:active {
   top: 0;
-  box-shadow: 0 2px 0 #002d18;
+  box-shadow: 0 2px 0 rgb(0, 44.8, 24);
 }
 
 .govuk-button--secondary {
   background-color: #f3f2f1;
-  box-shadow: 0 2px 0 #929191;
+  box-shadow: 0 2px 0 rgb(145.8, 145.2, 144.6);
 }
 .govuk-button--secondary, .govuk-button--secondary:link, .govuk-button--secondary:visited, .govuk-button--secondary:active, .govuk-button--secondary:hover {
   color: #0b0c0c;
 }
 .govuk-button--secondary:hover {
-  background-color: #dbdad9;
+  background-color: rgb(218.7, 217.8, 216.9);
 }
 .govuk-button--secondary:hover[disabled] {
   background-color: #f3f2f1;
@@ -1465,13 +1465,13 @@
 
 .govuk-button--warning {
   background-color: #d4351c;
-  box-shadow: 0 2px 0 #55150b;
+  box-shadow: 0 2px 0 rgb(84.8, 21.2, 11.2);
 }
 .govuk-button--warning, .govuk-button--warning:link, .govuk-button--warning:visited, .govuk-button--warning:active, .govuk-button--warning:hover {
   color: #ffffff;
 }
 .govuk-button--warning:hover {
-  background-color: #aa2a16;
+  background-color: rgb(169.6, 42.4, 22.4);
 }
 .govuk-button--warning:hover[disabled] {
   background-color: #d4351c;
@@ -1479,13 +1479,13 @@
 
 .govuk-button--inverse {
   background-color: #ffffff;
-  box-shadow: 0 2px 0 #144e81;
+  box-shadow: 0 2px 0 rgb(20.3, 78.4, 128.8);
 }
 .govuk-button--inverse, .govuk-button--inverse:link, .govuk-button--inverse:visited, .govuk-button--inverse:active, .govuk-button--inverse:hover {
   color: #1d70b8;
 }
 .govuk-button--inverse:hover {
-  background-color: #e8f1f8;
+  background-color: rgb(232.4, 240.7, 247.9);
 }
 .govuk-button--inverse:hover[disabled] {
   background-color: #ffffff;
@@ -2380,7 +2380,7 @@
   color: #d4351c;
 }
 .govuk-error-summary__list a:hover {
-  color: #942514;
+  color: rgb(148.4, 37.1, 19.6);
 }
 .govuk-error-summary__list a:active {
   color: #d4351c;

data/app/assets/stylesheets/katalyst/govuk/components/combobox/_index.scss

@@ -0,0 +1,100 @@
+// assumes that hotwire_combobox is in the load paths, implies dartsass-rails is the compiler
+@use "hotwire_combobox";
+
+@import "govuk-frontend/dist/govuk/base";
+@import "govuk-frontend/dist/govuk/components/error-message/index";
+@import "govuk-frontend/dist/govuk/components/hint/index";
+@import "govuk-frontend/dist/govuk/components/label/index";
+
+// Based on components/select
+@include govuk-exports("govuk/component/combobox") {
+  .hw-combobox:has(.govuk-combobox) {
+    --hw-border-radius: 0;
+    --hw-border-width--slim: #{$govuk-border-width-form-element};
+    --hw-border-color: #{$govuk-input-border-colour};
+    --hw-focus-color: #{$govuk-focus-colour};
+    --hw-combobox-width: 100%;
+    --hw-combobox-width--multiple: 100%;
+    --hw-active-bg-color: #{govuk-colour("blue")};
+    --hw-padding--slim: #{govuk-spacing(1)};
+    --hw-padding--slimmer: #{govuk-spacing(1)};
+    --hw-padding--thick: #{govuk-spacing(1)};
+    --hw-font-size: 1rem;
+    --hw-line-height: 1.25;
+
+    display: flex;
+
+    .hw-combobox__main__wrapper {
+      // This min-width was chosen because:
+      // - it makes the Select wider than it is tall (which is what users expect)
+      // - 11.5em matches the 'length-10' variant of the input component
+      // - it fits comfortably on screens as narrow as 240px wide
+      min-width: 11.5em;
+      max-width: var(--text-width, 100%);
+
+      display: flex;
+      min-height: 2.5rem;
+      align-items: center;
+
+      // Default user agent colours for selects can have low contrast,
+      // and may look disabled (#2435)
+      color: $govuk-text-colour;
+      background-color: govuk-colour("white");
+    }
+
+    .hw-combobox__main__wrapper:focus-within {
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+      // Ensure outline appears outside of the element
+      outline-offset: 0;
+      // Double the border by adding its width again. Use `box-shadow` to do
+      // this instead of changing `border-width` (which changes element size)
+      // and since `outline` is already used for the yellow focus state.
+      box-shadow: inset 0 0 0 $govuk-border-width-form-element;
+    }
+
+    .govuk-combobox {
+      @include govuk-font($size: 16, $line-height: 1.25);
+
+      // override input styles from form/govuk
+      border: none;
+      outline: none;
+      box-shadow: none;
+      width: 100%;
+      padding: 0;
+      height: unset;
+    }
+
+    // disabled
+    &:has(.govuk-combobox:disabled) {
+      opacity: 0.5;
+      color: inherit;
+      cursor: not-allowed;
+    }
+
+    // extend existing hover/active styles (--hw-active-bg-color)
+    .hw-combobox__option:hover,
+    .hw-combobox__option--navigated,
+    .hw-combobox__option--selected {
+      color: govuk-colour("white");
+    }
+
+    .hw-combobox__dialog__input {
+      width: 100%;
+    }
+
+    .hw-combobox__listbox {
+      left: -$govuk-border-width-form-element;
+      right: -$govuk-border-width-form-element;
+      top: calc(100% + $govuk-border-width-form-element * 2 + 0.2rem);
+      width: unset;
+    }
+  }
+
+  .govuk-combobox--error {
+    border-color: $govuk-error-colour;
+
+    .hw-combobox__main__wrapper:focus-within {
+      border-color: $govuk-input-border-colour;
+    }
+  }
+}

data/app/assets/stylesheets/katalyst/govuk/components/richtextarea/_index.scss

@@ -2,12 +2,11 @@
 @import "govuk-frontend/dist/govuk/components/hint/index";
 @import "govuk-frontend/dist/govuk/components/label/index";
 
-// Based on components/textarea
 @include govuk-exports("govuk/component/richtextarea") {
   .govuk-richtextarea {
     @include govuk-font($size: 19, $line-height: 1.25);
 
-    box-sizing: border-box; // should this be global?
+    box-sizing: border-box;
     display: block;
     width: 100%;
     // min-height inherited from trix-editor styles
@@ -26,8 +25,8 @@
       // Ensure outline appears outside of the element
       outline-offset: 0;
       // Double the border by adding its width again. Use `box-shadow` to do
-      // this instead of changing `border-width` (which changes element size) and
-      // since `outline` is already used for the yellow focus state.
+      // this instead of changing `border-width` (which changes element size)
+      // and since `outline` is already used for the yellow focus state.
       box-shadow: inset 0 0 0 $govuk-border-width-form-element;
     }
 

data/lib/katalyst/govuk/formbuilder/builder.rb

@@ -157,7 +157,7 @@ module Katalyst
         # @param form_group [Hash] configures the form group
         # @option form_group classes [Array,String] sets the form group's classes
         # @option form_group kwargs [Hash] additional attributes added to the form group
-        # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
+        # @param & [Block] arbitrary HTML that will be rendered between the hint and the input
         # @return [ActiveSupport::SafeBuffer] HTML output
         #
         # @example A rich text area with injected content
@@ -186,6 +186,46 @@ module Katalyst
           ).html
         end
 
+        # Generates a +combobox+ element that uses Hotwire Combobox to generate a combobox selection element.
+        # @see https://hotwirecombobox.com
+        # @see https://github.com/josefarias/hotwire_combobox
+        #
+        # @param attribute_name [Symbol] The name of the attribute
+        # @param options_or_src [Array] The +option+ values or a source path for async combobox
+        # @param options [Hash] Options hash passed through to the +combobox+ helper
+        # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+.
+        #   When a +Proc+ is supplied the hint will be wrapped in a +div+ instead of a +span+
+        # @option hint text [String] the hint text
+        # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
+        # @param label [Hash,Proc] configures or sets the associated label content
+        # @option label text [String] the label text
+        # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
+        # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
+        # @option label hidden [Boolean] control the visibility of the label.
+        #   Hidden labels will still be read by screenreaders
+        # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
+        # @param form_group [Hash] configures the form group
+        # @option form_group kwargs [Hash] additional attributes added to the form group
+        # @return [ActiveSupport::SafeBuffer] HTML output
+        #
+        # @example A combobox that allows the user to choose from a list of states
+        #
+        #   = f.combobox "state", State.all
+        #
+        # @example A combobox that allows the user to choose from an asynchronous states endpoint
+        #
+        #   = f.combobox "state", states_path
+        #
+        # @example A multi-select combobox that allows the user to choose multiple states
+        #
+        #   = f.combobox "state", State.all, multiselect_chip_src: states_chips_path
+        #
+        def govuk_combobox(attribute_name, options_or_src = [], options: {}, label: {}, hint: {}, form_group: {},
+                           caption: {}, **, &)
+          Elements::Combobox.new(self, object_name, attribute_name, options_or_src,
+                                 options:, label:, hint:, form_group:, caption:, **, &).html
+        end
+
         # Keep track of whether we are inside a fieldset
         # This allows labels to default to bold ("s") normally but use the default otherwise
         def fieldset_context

data/lib/katalyst/govuk/formbuilder/elements/combobox.rb

@@ -0,0 +1,60 @@
+# 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
+
+          def initialize(builder, object_name, attribute_name, options_or_src, options:, form_group:, label:, hint:,
+                         caption:, **kwargs, &block)
+            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
+          end
+
+          def html
+            GOVUKDesignSystemFormBuilder::Containers::FormGroup.new(*bound, **@form_group).html do
+              safe_join([label_element, hint_element, error_element, combobox])
+            end
+          end
+
+          private
+
+          def combobox
+            @builder.combobox(@attribute_name, @options_or_src, **@options, **attributes(@html_attributes), &@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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: katalyst-govuk-formbuilder
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Katalyst Interactive
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-09-16 00:00:00.000000000 Z
+date: 2024-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: govuk_design_system_formbuilder
@@ -37,13 +37,14 @@ files:
 - app/assets/builds/katalyst/govuk/formbuilder.js
 - app/assets/builds/katalyst/govuk/formbuilder.min.js
 - app/assets/config/katalyst-govuk-formbuilder.js
+- app/assets/stylesheets/katalyst/govuk/components/combobox/_index.scss
 - app/assets/stylesheets/katalyst/govuk/components/richtextarea/_index.scss
-- app/assets/stylesheets/katalyst/govuk/components/richtextarea/_richtextarea.scss
 - app/assets/stylesheets/katalyst/govuk/formbuilder.scss
 - config/importmap.rb
 - lib/katalyst/govuk/formbuilder.rb
 - lib/katalyst/govuk/formbuilder/builder.rb
 - lib/katalyst/govuk/formbuilder/containers/fieldset_context.rb
+- lib/katalyst/govuk/formbuilder/elements/combobox.rb
 - lib/katalyst/govuk/formbuilder/elements/label.rb
 - lib/katalyst/govuk/formbuilder/elements/legend.rb
 - lib/katalyst/govuk/formbuilder/elements/rich_text_area.rb

data/app/assets/stylesheets/katalyst/govuk/components/richtextarea/_richtextarea.scss

@@ -1,2 +0,0 @@
-@import "govuk-frontend/dist/govuk/base";
-@import "./index";