govuk_publishing_components 62.3.0 → 63.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 877d3b494b073557d9eb1ead7a807dd6a1b669ede799d5cc14646f5b7dfe9e27
-  data.tar.gz: f5b477c3685c7405690997f8668477d65e45be54976e5115ff62e9b035e160be
+  metadata.gz: 6d7be3bd8faf1d55b317bda8101dce15b87de9bc7ef96a090e8394d8f174442f
+  data.tar.gz: 77796278e71f2963c5898e84f587ea9ba08bf599ff24a9a7a785aeda2d3d5226
 SHA512:
-  metadata.gz: 32838e5c58c4ccbe1c076cc94d210fac0d58a3d9573bb1f05dfba29d06c448a53b312fe8c8cebfb4b0737ffac4885520e2ea4894d5b22fd801ebf70c0ee80b38
-  data.tar.gz: ae7fbc9735a2e96482c6098a8c1e3f1f370e700f1da77f93ba5c11cd67bb51eb7e0e924fdf436f3666eed64d213006f8adfac19a3f1f0a7775917b32c04b95d3
+  metadata.gz: 61d1ad004cbfbcc2eee95cfc4a17930fcb7d38c7bb20b7cbec01861d0aaf35975af38e08d91216a339a1cee6efb0a628acc658439518eb5225c05acf1182907e
+  data.tar.gz: a2d709fbe8a6a84a7b0773db6f276d4a02595853039a6c0085a85c9536c048f47faf97ef7356ce7294e7f3e563b0f393505792b55c8dddcad59ac92580af535d

data/app/assets/javascripts/govuk_publishing_components/components/add-another.js

@@ -1,3 +1,4 @@
+//= require sortablejs/Sortable.js
 window.GOVUK = window.GOVUK || {}
 window.GOVUK.Modules = window.GOVUK.Modules || {};
 
@@ -27,6 +28,9 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
     this.createAddAnotherButton()
     this.createRemoveButtons()
     this.removeEmptyFieldset()
+    if (this.module.dataset.sortable === 'true') {
+      this.makeSortable()
+    }
     this.updateFieldsetsAndButtons()
   }
 
@@ -102,12 +106,14 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
     visibleFields.forEach(function (field, index) {
       field.querySelector('legend').textContent = this.module.dataset.fieldsetLegend + ' ' + (index + 1)
 
-      var trackedRemoveButton = field.parentNode.querySelector('.js-add-another__remove-button[data-ga4-event]')
+      var trackedButtons = field.parentNode.querySelectorAll(
+        '.js-add-another__remove-button[data-ga4-event], .gem-c-add-another__move-button[data-ga4-event]'
+      )
 
-      if (trackedRemoveButton) {
-        trackedRemoveButton.dataset.indexSection = this.startIndex + index
-        trackedRemoveButton.dataset.indexSectionCount = this.indexSectionCount || visibleFields.length
-      }
+      trackedButtons.forEach(function (button) {
+        button.dataset.indexSection = this.startIndex + index
+        button.dataset.indexSectionCount = this.indexSectionCount || visibleFields.length
+      }.bind(this))
     }.bind(this))
 
     if (this.module.dataset.emptyFields === 'false') {
@@ -117,6 +123,10 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
       )
     }
 
+    if (this.module.dataset.sortable === 'true') {
+      this.disableTopAndBottomButtons()
+    }
+
     var trackedAddAnotherButton = this.module.querySelector('.js-add-another__add-button[data-ga4-event]')
 
     if (trackedAddAnotherButton) {
@@ -125,15 +135,30 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
     }
   }
 
+  // Disable the top "Move up" and bottom "Move down" buttons when the list is sortable.
+  AddAnother.prototype.disableTopAndBottomButtons = function () {
+    this.module.querySelectorAll('.gem-c-add-another__move-button').forEach(function (button) {
+      button.removeAttribute('disabled')
+    })
+
+    var topMoveUpButton = this.module.querySelector('.js-add-another__fieldset:first-of-type .gem-c-add-another__move-button[data-action="move-up"]')
+    topMoveUpButton.setAttribute('disabled', true)
+
+    var bottomMoveDownButton = this.module.querySelector('.js-add-another__fieldset:last-of-type .gem-c-add-another__move-button[data-action="move-down"]')
+    bottomMoveDownButton.setAttribute('disabled', true)
+  }
+
   AddAnother.prototype.addNewFieldset = function (event) {
-    var button = event.target
     var newFieldsetTemplate = this.module.querySelector('.js-add-another__empty-template')
     var newFieldset = newFieldsetTemplate.content.cloneNode(true).children[0]
     newFieldset.classList.add('js-add-another__fieldset')
     this.createRemoveButton(newFieldset, this.removeNewFieldset.bind(this))
-    button.before(newFieldset)
+    newFieldsetTemplate.before(newFieldset)
 
-    this.incrementAttributes(newFieldsetTemplate.content)
+    this.updateAttributes(newFieldsetTemplate.content)
+    if (this.module.dataset.sortable === 'true') {
+      this.makeSortable()
+    }
     this.updateFieldsetsAndButtons()
 
     // Initialise any modules included in new fieldset
@@ -160,7 +185,7 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
   }
 
   // Set attribute values for id, for and name of supplied fieldset
-  AddAnother.prototype.incrementAttributes = function (fieldset) {
+  AddAnother.prototype.updateAttributes = function (fieldset, newIndex = null) {
     var matcher = /(.*[_[])([0-9]+)([_\]].*?)$/
     fieldset
       .querySelectorAll('label, input, select, textarea')
@@ -169,11 +194,117 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
           var value = element.getAttribute(attribute)
           var matched = matcher.exec(value)
           if (!matched) return
-          var index = parseInt(matched[2], 10) + 1
+          var index = newIndex == null ? (parseInt(matched[2], 10) + 1) : newIndex
           element.setAttribute(attribute, matched[1] + index + matched[3])
         })
       })
   }
 
+  AddAnother.prototype.makeSortable = function () {
+    this.removeMoveButtons()
+    this.addMoveButtons()
+    this.hideOrderInputs()
+    this.sortableList = window.Sortable.create(this.module, {
+      dataIdAttr: 'data-sortable-id',
+      disabled: true
+    })
+  }
+
+  AddAnother.prototype.getOrderInputs = function () {
+    return this.module.querySelectorAll('.js-add-another__fieldset:not([hidden]) .js-add-another__order-input input')
+  }
+
+  AddAnother.prototype.hideOrderInputs = function () {
+    this.getOrderInputs().forEach(function (orderInput) {
+      orderInput.closest('.js-add-another__order-input').hidden = true
+    })
+  }
+
+  AddAnother.prototype.addMoveButtons = function () {
+    var visibleFields = this.module.querySelectorAll('.js-add-another__fieldset:not([hidden])')
+    visibleFields.forEach(function (field, index) {
+      field.dataset.sortableId = 'js-add-another__sortable-' + index + '-fieldset'
+      var wrapper = document.createElement('div')
+      wrapper.className = 'gem-c-add-another__move-button-wrapper'
+      this.addButton(wrapper, 'move-up')
+      this.addButton(wrapper, 'move-down')
+      field.prepend(wrapper)
+    }.bind(this))
+  }
+
+  AddAnother.prototype.addButton = function (wrapper, action) {
+    var button = document.createElement('button')
+    button.className = 'govuk-button gem-c-button--secondary-quiet gem-c-add-another__move-button'
+    button.innerText = action === 'move-up' ? 'Move up' : 'Move down'
+    button.dataset.action = action
+    if (!this.disableGa4) {
+      button.dataset.ga4Event = this.createEventData({ action: action })
+    }
+
+    button.addEventListener('click', this.moveFieldset.bind(this))
+    wrapper.prepend(button)
+  }
+
+  AddAnother.prototype.moveFieldset = function (event) {
+    event.preventDefault()
+
+    var button = event.currentTarget
+    var action = button.dataset.action
+    var fieldset = button.closest('.js-add-another__fieldset')
+
+    var sortableId = fieldset.dataset.sortableId
+
+    var order = this.sortableList.toArray()
+    var index = order.indexOf(sortableId)
+
+    // pull the item we're moving out of the order
+    order.splice(index, 1)
+
+    // put it back in at the correct position
+    if (action === 'move-down') {
+      order.splice(index + 1, 0, sortableId)
+    } else if (action === 'move-up') {
+      order.splice(index - 1, 0, sortableId)
+    }
+
+    this.sortableList.sort(order, true)
+    this.updateFieldsetsAndButtons()
+
+    var visibleFields = this.module.querySelectorAll('.js-add-another__fieldset:not([hidden])')
+    visibleFields.forEach(function (field, index) {
+      this.updateAttributes(field, index)
+    }.bind(this))
+
+    var triggeredByKeyboard = event.detail === 0
+    if (triggeredByKeyboard) {
+      this.preserveElementFocus(button, fieldset, action, visibleFields)
+    }
+
+    this.updateOrderInputs()
+  }
+
+  AddAnother.prototype.preserveElementFocus = function (button, fieldset, action, visibleFields) {
+    let target = button
+    if (action === 'move-up' && fieldset === visibleFields[0]) {
+      target = button.parentNode.querySelector('button[data-action="move-down"]')
+    } else if (action === 'move-down' && fieldset === visibleFields[visibleFields.length - 1]) {
+      target = button.parentNode.querySelector('button[data-action="move-up"]')
+    }
+    target.focus()
+  }
+
+  AddAnother.prototype.removeMoveButtons = function () {
+    var wrappers = this.module.querySelectorAll('.gem-c-add-another__move-button-wrapper')
+    wrappers.forEach((button) => {
+      button.remove()
+    })
+  }
+
+  AddAnother.prototype.updateOrderInputs = function () {
+    this.getOrderInputs().forEach(function (orderInput, index) {
+      orderInput.value = index + 1
+    })
+  }
+
   Modules.AddAnother = AddAnother
 })(window.GOVUK.Modules)

data/app/assets/stylesheets/govuk_publishing_components/_all_components.scss

@@ -65,7 +65,7 @@
 @import "components/panel";
 @import "components/password-input";
 @import "components/phase-banner";
-@import "components/previous-and-next-navigation";
+@import "components/pagination";
 @import "components/print-link";
 @import "components/published-dates";
 @import "components/radio";

data/app/assets/stylesheets/govuk_publishing_components/components/_add-another.scss

@@ -11,4 +11,22 @@
   .js-add-another__remove-button--hidden {
     display: none;
   }
+
+  .gem-c-fieldset {
+    position: relative;
+  }
+
+  .gem-c-add-another__move-button[disabled] {
+    display: none;
+  }
+
+  .gem-c-add-another__move-button-wrapper {
+    position: absolute;
+    top: 0;
+    right: 0;
+  }
+
+  .gem-c-add-another__move-button {
+    margin-left: govuk-spacing(2);
+  }
 }

data/app/assets/stylesheets/govuk_publishing_components/components/_figure.scss

@@ -1,46 +1,24 @@
 @import "govuk_publishing_components/individual_component_support";
 
+$gap: govuk-spacing(1);
+
 .gem-c-figure {
-  border-top: 1px solid $govuk-border-colour;
-  padding-top: govuk-spacing(3);
   margin: 0;
-  margin-bottom: govuk-spacing(8);
-  @include govuk-clearfix;
-
-  @include govuk-media-query($until: tablet) {
-    margin-bottom: govuk-spacing(6);
-  }
+  display: table;
 }
 
 .gem-c-figure__image {
-  display: block;
-  width: 100%;
-
-  @include govuk-media-query($from: tablet) {
-    float: inline-start;
-    width: 50%;
-  }
+  max-width: 100%;
+  display: table-row;
 }
 
 .gem-c-figure__figcaption {
-  @include govuk-font(16);
-
-  @include govuk-media-query($from: tablet) {
-    display: block;
-    vertical-align: top;
-    box-sizing: border-box;
-    float: inline-end;
-    padding-inline-start: govuk-spacing(3);
-    width: 50%;
-  }
-
-  @include govuk-media-query($until: tablet) {
-    margin-top: govuk-spacing(2);
-  }
+  display: table-caption;
+  caption-side: bottom;
 }
 
 .gem-c-figure__figcaption-text {
-  margin: 0;
-  margin-bottom: govuk-spacing(2);
-  @include govuk-font(16);
+  margin: govuk-spacing(2) 0 0 0;
+  color: $govuk-secondary-text-colour;
+  @include govuk-font(19);
 }

data/app/assets/stylesheets/govuk_publishing_components/components/_image-card.scss

@@ -170,53 +170,6 @@
   }
 }
 
-// Ensure the YouTube video has a fluid width
-// https://alistapart.com/article/creating-intrinsic-ratios-for-video/
-.gem-c-image-card__youtube-video-embed {
-  position: relative;
-  padding-bottom: 56.25%; /* 16:9 */
-  height: 0;
-}
-
-.gem-c-image-card__youtube-video-embed iframe {
-  position: absolute;
-  top: 0;
-  left: 0;
-  width: 100%;
-  height: 100%;
-}
-
-.gem-c-image-card__youtube-thumbnail-image-container {
-  position: relative;
-
-  &::before {
-    background: url("govuk_publishing_components/youtube-play-icon.png");
-    background: url("govuk_publishing_components/youtube-play-icon.svg"), linear-gradient(transparent, transparent);
-    background-repeat: no-repeat;
-    background-position: 50%;
-    background-size: 75px auto;
-    content: "";
-    height: 100%;
-    left: 0;
-    position: absolute;
-    top: 0;
-    width: 100%;
-    z-index: 1;
-  }
-}
-
-.gem-c-image-card__youtube-thumbnail-image {
-  filter: brightness(.9);
-}
-
-.gem-c-image-card__youtube-thumbnail-container-text {
-  margin-top: 10px;
-}
-
-.gem-c-image-card__youtube-thumbnail-container:focus .gem-c-image-card__youtube-thumbnail-container-text {
-  @include govuk-focused-text;
-}
-
 // stylelint-disable declaration-no-important
 @include govuk-media-query($media-type: print) {
   .gem-c-image-card__title[class*="govuk-heading-"] {

data/app/assets/stylesheets/govuk_publishing_components/components/{_previous-and-next-navigation.scss → _pagination.scss}

@@ -3,7 +3,7 @@
 
 // stylelint-disable declaration-no-important
 @include govuk-media-query($media-type: print) {
-  .govuk-pagination * {
+  .gem-c-pagination * {
     color: $govuk-print-text-colour !important;
   }
 }

data/app/assets/stylesheets/govuk_publishing_components/components/govspeak/_images.scss

@@ -13,21 +13,23 @@
   }
 
   figure {
-    width: 100%;
-    clear: both;
-    overflow: hidden;
     margin: 0 0 govuk-spacing(4) 0;
+    display: table;
 
     img {
-      display: inline;
-      text-align: center;
-      width: auto;
-      height: auto;
       max-width: 100%;
+      display: table-row;
     }
 
     figcaption {
-      @include govuk-font($size: 16);
+      display: table-caption;
+      caption-side: bottom;
+    }
+
+    figcaption p {
+      margin: govuk-spacing(2) 0 0 0;
+      color: $govuk-secondary-text-colour;
+      @include govuk-font(19);
     }
   }
 }

data/app/views/govuk_publishing_components/components/_add_another.html.erb

@@ -6,6 +6,7 @@
   add_button_text ||= "Add another"
   empty_fields ||= false
   disable_ga4 ||= nil
+  sortable ||= false
 
   component_helper = GovukPublishingComponents::Presenters::ComponentWrapperHelper.new(local_assigns)
   component_helper.add_class("gem-c-add-another")
@@ -15,6 +16,7 @@
     fieldset_legend:,
     empty_fields:,
     disable_ga4:,
+    sortable:,
   })
 %>
 
@@ -26,6 +28,14 @@
         legend_text: "#{fieldset_legend} #{index + 1}",
         heading_size: "m",
       } do %>
+        <% if sortable %>
+          <div class="js-add-another__order-input">
+            <label class="gem-c-label govuk-label">
+              Position<span class='govuk-visually-hidden'> for <%= fieldset_legend %></span>
+              <%= item[:order_input] %>
+            </label>
+          </div>
+        <% end %>
         <div class="js-add-another__destroy-checkbox">
           <%= item[:destroy_checkbox] %>
         </div>

data/app/views/govuk_publishing_components/components/_breadcrumbs.html.erb

@@ -5,6 +5,8 @@
   breadcrumbs ||= []
   collapse_on_mobile ||= false
   inverse ||= false
+  local_assigns[:aria] ||= {}
+  local_assigns[:aria][:label] ||= "Breadcrumb"
 
   breadcrumb_presenter = GovukPublishingComponents::Presenters::Breadcrumbs.new(breadcrumbs)
 
@@ -15,7 +17,6 @@
 
   component_helper = GovukPublishingComponents::Presenters::ComponentWrapperHelper.new(local_assigns)
   component_helper.add_class(classes.join(" "))
-  component_helper.add_aria_attribute({ label: "Breadcrumb" })
   component_helper.add_data_attribute({ module: "ga4-link-tracker" })
 %>
 

data/app/views/govuk_publishing_components/components/_figure.html.erb

@@ -5,6 +5,7 @@
   credit ||= ""
   src ||= nil
   local_assigns[:lang] ||= "en"
+  local_assigns[:margin_bottom] ||= 8
   component_helper = GovukPublishingComponents::Presenters::ComponentWrapperHelper.new(local_assigns)
   component_helper.add_class("gem-c-figure")
 %>

data/app/views/govuk_publishing_components/components/_image_card.html.erb

@@ -5,7 +5,7 @@
   brand ||= false
 
   brand_helper = GovukPublishingComponents::AppHelpers::BrandHelper.new(brand)
-  card_helper = GovukPublishingComponents::Presenters::ImageCardHelper.new(local_assigns, brand_helper)
+  card_helper = GovukPublishingComponents::Presenters::ImageCardHelper.new(local_assigns)
   shared_helper = GovukPublishingComponents::Presenters::SharedHelper.new(local_assigns)
   component_helper = GovukPublishingComponents::Presenters::ComponentWrapperHelper.new(local_assigns)
   component_helper.add_class("gem-c-image-card")
@@ -33,7 +33,6 @@
   ]
   extra_link_classes << brand_helper.color_class
 
-  component_helper.add_data_attribute({ module: "image-card" }) if card_helper.youtube_video_id
   component_helper.set_lang(card_helper.lang)
 %>
 <% if card_helper.href || card_helper.extra_details.any? %>

data/app/views/govuk_publishing_components/components/_layout_for_public.html.erb

@@ -71,10 +71,12 @@
     <%= javascript_tag nonce: true do -%>
       document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');
     <% end %>
-    <%= render "govuk_publishing_components/components/cookie_banner", layout_helper.cookie_banner_data %>
-    <%= render "govuk_publishing_components/components/skip_link", {
-      href: "#content",
-    } %>
+    <% I18n.with_locale(:en) do %>
+      <%= render "govuk_publishing_components/components/cookie_banner", layout_helper.cookie_banner_data %>
+      <%= render "govuk_publishing_components/components/skip_link", {
+        href: "#content",
+      } %>
+    <% end %>
     <% unless omit_header %>
       <% if show_cross_service_header %>
         <%= render "govuk_publishing_components/components/cross_service_header", {
@@ -121,15 +123,19 @@
 
     <% unless omit_feedback_form %>
       <div class="govuk-width-container">
-        <%= render "govuk_publishing_components/components/feedback" %>
+        <% I18n.with_locale(:en) do %>
+          <%= render "govuk_publishing_components/components/feedback" %>
+        <% end %>
       </div>
     <% end %>
 
     <% unless local_assigns[:hide_footer_links] %>
-      <%= render "govuk_publishing_components/components/layout_footer", {
-        navigation: omit_footer_navigation ? nil : layout_helper.footer_navigation,
-        meta: layout_helper.footer_meta,
-      } %>
+      <% I18n.with_locale(:en) do %>
+        <%= render "govuk_publishing_components/components/layout_footer", {
+          navigation: omit_footer_navigation ? nil : layout_helper.footer_navigation,
+          meta: layout_helper.footer_meta,
+        } %>
+      <% end %>
     <% end %>
     <%= javascript_include_tag "application", type: "module" %>
     <% if GovukPublishingComponents::Config.use_es6_components %>

data/app/views/govuk_publishing_components/components/_pagination.html.erb

@@ -0,0 +1,21 @@
+<%
+  add_gem_component_stylesheet("pagination")
+  disable_ga4 ||= false
+  items ||= nil
+
+  component_helper = GovukPublishingComponents::Presenters::ComponentWrapperHelper.new(local_assigns)
+  component_helper.add_class("gem-c-pagination govuk-pagination")
+  component_helper.add_class("govuk-pagination--block") if items.blank?
+  component_helper.add_aria_attribute({ label: t("components.pagination.pagination") })
+  component_helper.add_data_attribute({ module: "ga4-link-tracker" }) unless disable_ga4
+
+  pagination_helper = GovukPublishingComponents::Presenters::PaginationHelper.new(local_assigns)
+
+  if pagination_helper.has_links?
+%>
+  <%= tag.nav(**component_helper.all_attributes) do %>
+    <%= pagination_helper.prev_link %>
+    <%= pagination_helper.page_links %>
+    <%= pagination_helper.next_link %>
+  <% end %>
+<% end %>

data/app/views/govuk_publishing_components/components/docs/add_another.yml

@@ -121,3 +121,49 @@ examples:
           <option value="92bbe2da-8d5f-480b-8da1-50b18e317654">Accelerated Capability Environment</option>
           </select>
         <div class="govuk-form-group">
+  sortable:
+    description: | 
+      Adding `sortable` to the component will allow users to rearrange the items in the list.
+      
+      This component uses SortableJS. When JavaScript is disabled a set of inputs will be shown allowing users to 
+      provide an order index for each item.
+      
+      For this to work, each field must have an `order_index` input provided.
+    data:
+      fieldset_legend: "Person"
+      add_button_text: "Add another person"
+      sortable: true
+      items:
+        - fields: >
+            <div class="govuk-form-group">
+              <label for="sortable_person_0_name" class="gem-c-label govuk-label">Full name</label>
+              <input class="gem-c-input govuk-input" id="sortable_person_0_name" name="person[0]name" value="Person A">
+            </div>
+          destroy_checkbox: >
+            <div class="govuk-checkboxes" data-module="govuk-checkboxes">
+              <div class="govuk-checkboxes__item">
+                <input type="checkbox" name="person[0][_destroy]" id="sortable_person_0__destroy" class="govuk-checkboxes__input">
+                <label for="sortable_person_0__destroy" class="govuk-label govuk-checkboxes__label">Delete</label>
+              </div>
+            </div>
+          order_input: >
+            <input class="gem-c-input govuk-input govuk-input--width-2" id="sortable_person_0_order" name="person[0]order" value="1">
+        - fields: >
+            <div class="govuk-form-group">
+              <label for="sortable_person_1_name" class="gem-c-label govuk-label">Full name</label>
+              <input class="gem-c-input govuk-input" id="sortable_person_1_name" name="person[1]name" value="Person B">
+            </div>
+          destroy_checkbox: >
+            <div class="govuk-checkboxes" data-module="govuk-checkboxes">
+              <div class="govuk-checkboxes__item">
+                <input type="checkbox" name="person[1][_destroy]" id="sortable_person_1__destroy" class="govuk-checkboxes__input">
+                <label for="sortable_person_1__destroy" class="govuk-label govuk-checkboxes__label">Delete</label>
+              </div>
+            </div>
+          order_input: >
+            <input class="gem-c-input govuk-input govuk-input--width-2" id="sortable_person_1_order" name="person[1]order" value="2">
+      empty:
+        <div class="govuk-form-group">
+          <label for="sortable_person_2_name" class="gem-c-label govuk-label">Full name</label>
+          <input class="gem-c-input govuk-input" id="sortable_person_2_name" name="person[2]name">
+        </div>

data/app/views/govuk_publishing_components/components/docs/figure.yml

@@ -1,5 +1,5 @@
 name: Figure
-description: A figure containing an image that never exceeds the component’s width
+description: A figure containing an image and optional caption.
 body: |
   A figure should be used for images that are referenced within a page, but which can be moved around without affecting the flow of the page [(see guidance here)](https://developer.mozilla.org/en/docs/Web/HTML/Element/figure)
 
@@ -15,29 +15,30 @@ uses_component_wrapper_helper: true
 examples:
   default:
     data:
-      src: 'https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg'
+      src: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg
   figure_with_alt_text:
     data:
-      src: 'https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg'
-      alt: 'An image of the lords chamber'
+      src: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg
+      alt: An image of the lords chamber
   figure_with_caption:
+    description: The image will fill the available space but not exceed the width of the container or its own width. The caption will always be the same width as the image.
     data:
-      src: 'https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg'
-      alt: 'An image of the lords chamber'
-      caption: 'The Lords Chamber'
+      src: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg
+      alt: An image of the lords chamber
+      caption: The Lords Chamber on the 14th of August. A large number of people are in attendance, filling the seats in the lower and upper areas. Several people are wearing hats.
   right_to_left_with_caption:
     data:
-      src: 'https://assets.publishing.service.gov.uk/government/uploads/system/uploads/image_data/file/31637/s300_Visas_-_Website.jpg'
-      alt: 'تأشيرات'
-      caption: 'تأشيرات'
+      src: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/image_data/file/31637/s300_Visas_-_Website.jpg
+      alt: تأشيرات
+      caption: تأشيرات
     context:
       right_to_left: true
   figure_with_credit:
     data:
-      src: 'https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg'
-      credit: Wallis Crankled
+      src: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg
+      credit: Roger Harris
   figure_with_caption_and_credit:
     data:
-      src: 'https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg'
-      caption: The Lords Chamber
-      credit: Wallis Crankled
+      src: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/54374/s630_the_lords_chamber.jpg
+      caption: The Lords Chamber on the 14th of August. A large number of people are in attendance, filling the seats in the lower and upper areas. Several people are wearing hats.
+      credit: Roger Harris

data/app/views/govuk_publishing_components/components/docs/govspeak.yml

@@ -849,6 +849,7 @@ examples:
         <h5>This is a h5 title</h5>
         <h6>This is a h6 title</h6>
   image:
+    description: Govspeak images are styled to mimic the [figure component](/component-guide/figure).
     data:
       block: |
         <figure class="image embedded">
@@ -859,6 +860,7 @@ examples:
             <p>Deforested area. Credit: Blue Ventures-Garth Cripps</p>
           </figcaption>
         </figure>
+        <p>This is a regular paragraph of text to demonstrate the spacing between it and the image above.</p>
   lists:
     data:
       block: |