PLATUI-2918 add empty value

CHANGELOG.md

@@ -8,6 +8,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 For compatibility information see `govukFrontendVersion` and `hmrcFrontendVersion` in
 [LibDependencies](project/LibDependencies.scala)
 
+## [9.11.0] - 2024-05-09
+
+### Changed
+
+- Added an `emptyItem` parameter to AccessibleAutocomplete to provide an item with no value to the top of a list.
+
+### Compatible with
+
+- [hmrc/hmrc-frontend v6.17.0](https://github.com/hmrc/hmrc-frontend/releases/tag/v6.17.0)
+- [alphagov/govuk-frontend v5.3.0](https://github.com/alphagov/govuk-frontend/releases/tag/v5.3.0)
+
 ## [9.10.0] - 2024-04-24
 
 ### Changed

README.md

@@ -915,17 +915,13 @@ If you wish to change these values you can do so by providing an `AccessibleAuto
 ```
 
 There is a caveat currently with the `defaultValue` property, to use this option you will need to ensure
-that you have a placeholder item in your select element that has an empty value. You will also need to make sure none of
-your select items have the selected property set on them. See example below.
+that you have an empty item in your select element that has an empty value. You can do this with the `emptyItem` property. See example below.
 
 ```scala
 @govukSelect(Select(
         id = "sort",
         name = "sort",
         items = Seq(
-            SelectItem(
-                text = "Placeholder text"
-            ),
             SelectItem(
                 value = Some("published"),
                 text = "Recently published"
@@ -940,15 +936,16 @@ your select items have the selected property set on them. See example below.
         )
     ).asAccessibleAutocomplete(Some(
         AccessibleAutocomplete(
+            emptyItem = Some(""),
             defaultValue = Some("Recently updated"),
             showAllValues = true,
             autoSelect = false)
     )))
 ```
 
-More information on `defaultValue` property can be found [here](https://www.npmjs.com/package/accessible-autocomplete) under the `Null options` heading
+More information on `defaultValue` property can be found [here](https://www.npmjs.com/package/accessible-autocomplete) under the `Null options` heading.
 
-A preferred way would be to select a default value using the `selected` attribute on an select item instead of using the `defaultValue` property, as seen below.
+Another way would be to use the `emptyItem` parameter on `AccessibleAutocomplete` with `Some("String")`. This will act as an item with no value, the text will only show up when JavaScript is disabled. If the first or selected item has text in it, the text would show up in the input, preventing the rest of the list from showing with `AccessibleAutocomplete` without deleting the text first.
 
 ```scala
 @govukSelect(Select(
@@ -962,7 +959,6 @@ A preferred way would be to select a default value using the `selected` attribut
             SelectItem(
                 value = Some("updated"),
                 text = "Recently updated"
-                selected = true
             )
         ),
         label = Label(
@@ -971,11 +967,12 @@ A preferred way would be to select a default value using the `selected` attribut
     ).asAccessibleAutocomplete(Some(
         AccessibleAutocomplete(
             showAllValues = true,
-            autoSelect = false)
+            autoSelect = false,
+            emptyItem = Some("Select an item")
+        )
     )))
 ```
 
-
 ### Warning users before timing them out
 
 In order to meet the accessibility [WCAG 2.1 Principle 2: Operable](https://www.w3.org/TR/WCAG21/#operable) you must

play-frontend-hmrc-play-30/src/main/scala/uk/gov/hmrc/govukfrontend/views/implicits/RichSelectSupport.scala

@@ -63,6 +63,13 @@ trait RichSelectSupport {
     def withHeadingAndSectionCaption(heading: Content, sectionCaption: Content): Select =
       withHeadingLabel(select, heading, Some(sectionCaption))((sl, ul) => sl.copy(label = ul))
 
+    def withEmptyItem(emptyItemText: String): Select = {
+      val emptyItem: SelectItem = SelectItem.emptyItemObject(emptyItemText)
+      select.copy(
+        items = emptyItem +: select.items
+      )
+    }
+
     def asAccessibleAutocomplete(
       accessibleAutocomplete: Option[AccessibleAutocomplete] = None
     )(implicit messages: Messages): Select = {
@@ -72,15 +79,26 @@ trait RichSelectSupport {
           "data-show-all-values" -> accessibleAutocomplete.showAllValues.toString,
           "data-default-value"   -> accessibleAutocomplete.defaultValue.getOrElse(""),
           "data-min-length"      -> accessibleAutocomplete.minLength.map(_.toString).getOrElse(""),
+          "data-empty-item"      -> accessibleAutocomplete.emptyItem.map(_.toString).getOrElse(""),
           "data-module"          -> accessibleAutocomplete.dataModule
         )
 
       val dataAttributes =
         toMapOfDataAttributes(accessibleAutocomplete.getOrElse(AccessibleAutocomplete(None)))
 
       val maybeDataLanguage = Map("data-language" -> messages.lang.code).filterNot(_._2 == En.code)
-
-      select.copy(attributes = select.attributes ++ dataAttributes ++ maybeDataLanguage)
+      val maybeEmptyItem    = accessibleAutocomplete.map(_.emptyItem).getOrElse(None)
+
+      maybeEmptyItem match {
+        case None       =>
+          select.copy(attributes = select.attributes ++ dataAttributes ++ maybeDataLanguage)
+        case Some(text) =>
+          val emptyItem: SelectItem = SelectItem.emptyItemObject(text)
+          select.copy(
+            attributes = select.attributes ++ dataAttributes ++ maybeDataLanguage,
+            items = emptyItem +: select.items
+          )
+      }
     }
 
     private[views] def withName(field: Field): Select =

play-frontend-hmrc-play-30/src/main/scala/uk/gov/hmrc/govukfrontend/views/viewmodels/select/SelectItem.scala

@@ -31,7 +31,8 @@ final case class SelectItem(
 
 object SelectItem {
 
-  def defaultObject: SelectItem = SelectItem()
+  def defaultObject: SelectItem                          = SelectItem()
+  def emptyItemObject(emptyItemText: String): SelectItem = SelectItem(value = Some(""), text = emptyItemText)
 
   implicit def jsonReads: Reads[SelectItem] = (
     (__ \ "value").readsJsValueToString.map(Option[String]).orElse(Reads.pure(None)) and

play-frontend-hmrc-play-30/src/main/scala/uk/gov/hmrc/hmrcfrontend/views/viewmodels/accessibleautocomplete/AccessibleAutocomplete.scala

@@ -21,7 +21,8 @@ case class AccessibleAutocomplete(
     None, // Please read on the usage of the defaultValue property at https://www.npmjs.com/package/accessible-autocomplete under the `Null options` heading
   showAllValues: Boolean = false,
   autoSelect: Boolean = false,
-  minLength: Option[Int] = None
+  minLength: Option[Int] = None,
+  emptyItem: Option[String] = None
 ) {
   val dataModule: String = "hmrc-accessible-autocomplete"
 }

play-frontend-hmrc-play-30/src/test/scala/uk/gov/hmrc/govukfrontend/views/implicits/RichSelectSpec.scala

@@ -181,6 +181,7 @@ class RichSelectSpec extends AnyWordSpec with Matchers with MessagesHelpers with
           "data-show-all-values" -> "true",
           "data-auto-select"     -> "true",
           "data-min-length"      -> "",
+          "data-empty-item"      -> "",
           "data-module"          -> "hmrc-accessible-autocomplete"
         )
       )
@@ -200,6 +201,7 @@ class RichSelectSpec extends AnyWordSpec with Matchers with MessagesHelpers with
           "data-show-all-values" -> "true",
           "data-auto-select"     -> "true",
           "data-min-length"      -> "",
+          "data-empty-item"      -> "",
           "data-module"          -> "hmrc-accessible-autocomplete",
           "data-language"        -> "cy"
         )
@@ -227,6 +229,7 @@ class RichSelectSpec extends AnyWordSpec with Matchers with MessagesHelpers with
           "data-show-all-values" -> "true",
           "data-auto-select"     -> "true",
           "data-min-length"      -> "2",
+          "data-empty-item"      -> "",
           "data-module"          -> "hmrc-accessible-autocomplete",
           "data-language"        -> "cy"
         )
@@ -243,6 +246,7 @@ class RichSelectSpec extends AnyWordSpec with Matchers with MessagesHelpers with
           "data-show-all-values" -> "false",
           "data-auto-select"     -> "false",
           "data-min-length"      -> "",
+          "data-empty-item"      -> "",
           "data-module"          -> "hmrc-accessible-autocomplete"
         )
       )
@@ -258,6 +262,7 @@ class RichSelectSpec extends AnyWordSpec with Matchers with MessagesHelpers with
           "data-show-all-values" -> "false",
           "data-auto-select"     -> "false",
           "data-min-length"      -> "",
+          "data-empty-item"      -> "",
           "data-module"          -> "hmrc-accessible-autocomplete",
           "some-attr1"           -> "1",
           "some-attr2"           -> "2"