Add Published Dates component

- Used in Help Page
- Has Welsh and English translations
- Includes spec file, documentation

Commit audit trail:
- app/assets/stylesheets/components/_published-dates.scss https://github.com/alphagov/government-frontend/blob/af54031948650448b965ac274c3248d23658c4f6/app/assets/stylesheets/components/_published-dates.scss
- app/views/components/_published_dates.html.erb https://github.com/alphagov/government-frontend/blob/af54031948650448b965ac274c3248d23658c4f6/app/views/components/_published_dates.html.erb
- app/views/components/docs/published_dates.yml https://github.com/alphagov/government-frontend/blob/af54031948650448b965ac274c3248d23658c4f6/app/views/components/docs/published_dates.yml
- en.yml/cy.yml alphagov/government-frontend@450b53a
- spec/components/published_dates_spec.rb https://github.com/alphagov/government-frontend/blob/af54031948650448b965ac274c3248d23658c4f6/test/components/published_dates_test.rb

app/assets/stylesheets/components/_published-dates.scss

@@ -0,0 +1,53 @@
+@import "govuk_publishing_components/individual_component_support";
+
+.app-c-published-dates {
+  direction: ltr;
+  line-height: 1.45em;
+  color: govuk-colour("black");
+}
+
+.app-c-published-dates__toggle {
+  display: none;
+
+  .govuk-frontend-supported & {
+    display: inline-block;
+  }
+}
+
+.app-c-published-dates__change-history {
+  margin: govuk-spacing(4) 0;
+}
+
+.app-c-published-dates__list {
+  padding: 0;
+}
+
+.app-c-published-dates__change-item {
+  list-style-type: none;
+  margin-bottom: govuk-spacing(2);
+}
+
+.app-c-published-dates__change-date {
+  display: block;
+  @include govuk-font(16, $weight: bold);
+}
+
+.app-c-published-dates__change-note {
+  white-space: pre-line;
+}
+
+.app-c-published-dates--history {
+  padding-top: govuk-spacing(2);
+  border-top: 1px solid $govuk-border-colour;
+}
+
+.govuk-frontend-supported .app-c-published-dates .js-hidden {
+  display: none;
+  visibility: hidden;
+}
+
+@include govuk-media-query($media-type: print) {
+  .app-c-published-dates {
+    margin-top: 10mm;
+  }
+}

app/views/components/_published_dates.html.erb

@@ -0,0 +1,46 @@
+<% add_app_component_stylesheet("published-dates") %>
+<%
+  published ||= false
+  history ||= []
+  history = Array(history)
+  last_updated ||= false
+  link_to_history ||= false
+  shared_helper = GovukPublishingComponents::Presenters::SharedHelper.new(local_assigns)
+  classes = %w(app-c-published-dates)
+  classes << "app-c-published-dates--history" if history.any?
+  classes << shared_helper.get_margin_bottom if local_assigns[:margin_bottom]
+%>
+<% if published || last_updated %>
+  <h2 class="govuk-visually-hidden"><%= t('components.published_dates.hidden_heading') %></h2>
+<div class="<%= classes.join(' ') %>" <% if history.any? %>id="full-publication-update-history" data-module="gem-toggle"<% end %> lang="en">
+  <% if published %>
+    <%= t('components.published_dates.published', date: published) %>
+  <% end %>
+  <% if last_updated %>
+    <% if published %><br /><% end %><%= t('components.published_dates.last_updated', date: last_updated) %>
+    <% if link_to_history && history.empty? %>
+      &mdash; <a href="#history" class="app-c-published-dates__history-link govuk-link"><%= t('components.published_dates.see_all_updates', locale: :en) %></a>
+    <% elsif history.any? %>
+      <a href="#full-history"
+      class="app-c-published-dates__toggle govuk-link"
+      data-controls="full-history"
+      data-expanded="false"
+      data-toggled-text="&#45;&nbsp;<%= t('components.published_dates.hide_all_updates', locale: :en) %>"
+      data-module="ga4-event-tracker"
+      data-ga4-event="<%= {event_name: "select_content", type: "content history", section: "Footer"}.to_json %>"
+      data-ga4-expandable
+      >&#43;&nbsp;<%= t('components.published_dates.show_all_updates', locale: :en) %></a>
+      <div class="app-c-published-dates__change-history js-hidden" id="full-history">
+        <ol class="app-c-published-dates__list">
+          <% history.each do |change| %>
+            <li class="app-c-published-dates__change-item">
+              <time class="app-c-published-dates__change-date timestamp" datetime="<%= change[:timestamp] %>"><%= change[:display_time] %></time>
+              <p class="app-c-published-dates__change-note"><%= change[:note].strip %></p>
+            </li>
+          <% end %>
+        </ol>
+      </div>
+    <% end %>
+  <% end %>
+</div>
+<% end %>

app/views/components/docs/published_dates.yml

@@ -0,0 +1,48 @@
+name: Published dates
+description: Dates to reflect when content was published and updated
+accessibility_criteria: |
+  The published dates component must:
+
+    - indicate to users that the full history section can be expanded and collapsed
+    - inform the user of the state of the full history section (expanded or collapsed)
+    - be usable with a keyboard
+shared_accessibility_criteria:
+  - link
+examples:
+  default:
+    data:
+      published: 1st January 1990
+  just_last_updated_date:
+    data:
+      last_updated: 20th October 2016
+  with_last_updated_date:
+    data:
+      published: 1st January 1990
+      last_updated: 20th October 2016
+  link_to_page_history:
+    description: This will set up a link to a '#history' anchor on the page. This can be used to link to another instance of this component, see [Display Page History example](/component-guide/published_dates/display_page_history)
+    data:
+      published: 1st January 1990
+      last_updated: 20th October 2016
+      link_to_history: true
+  display_page_history:
+    description: This will set up an expandable section on the page, with a top border, to let users toggle the display of the page history.
+    data:
+      published: 1st January 1990
+      last_updated: 20th October 2016
+      history:
+      - display_time: 1st January 1990
+        note: First published
+        timestamp: 1990-01-01T15:42:37.000+00:00
+      - display_time: 20th July 1995
+        note: Updated to include information for 1994
+        timestamp: 1995-07-20T15:42:37.000+00:00
+      - display_time: 14th October 2000
+        note: Updated information on pupil premium reviews and what information schools need to publish on their websites.
+        timestamp: 2000-10-14T15:42:37.000+00:00
+  with_custom_margin_bottom:
+    description: |
+      The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). By default, the component does not have a bottom margin.
+    data:
+      published: 1st January 1990
+      margin_bottom: 8

config/initializers/dartsass.rb

@@ -2,6 +2,7 @@
   "application.scss" => "application.css",
   "components/_calendar.scss" => "components/_calendar.css",
   "components/_subscribe.scss" => "components/_subscribe.css",
+  "components/_published-dates.scss" => "components/_published-dates.css",
   "views/_calendars.scss" => "views/_calendars.css",
   "views/_cookie-settings.scss" => "views/_cookie-settings.css",
   "views/_csv_preview.scss" => "views/_csv_preview.css",

config/locales/cy.yml

@@ -73,6 +73,14 @@ cy:
     summer: Gŵyl banc yr haf
     year: Blwyddyn
   cancel:
+  components:
+    published_dates:
+      hidden_heading:
+      hide_all_updates: cuddio pob diweddariad
+      last_updated: Diweddarwyd ddiwethaf ar %{date}
+      published: Cyhoeddwyd ar %{date}
+      see_all_updates: gweld pob diweddariad
+      show_all_updates: dangos pob diweddariad
   common:
     add_holiday_ics: Ychwanegu'r gwyliau banc %{for_nation} at eich calendr (ICS, 14KB)
     bank_holiday_benefits_html: Efallai bydd gwyliau banc yn effeithio ar <a href="/how-to-have-your-benefits-paid" class="govuk-link">sut a phryd caiff eich budd-daliadau eu talu</a>.

config/locales/en.yml

@@ -73,6 +73,14 @@ en:
     summer: Summer bank holiday
     year: Year
   cancel: cancel
+  components:
+    published_dates:
+      hidden_heading: Updates to this page
+      hide_all_updates: hide all updates
+      last_updated: Last updated %{date}
+      published: Published %{date}
+      see_all_updates: See all updates
+      show_all_updates: show all updates
   common:
     add_holiday_ics: Add bank holidays %{for_nation} to your calendar (ICS, 14KB)
     bank_holiday_benefits_html: Bank holidays might affect <a href="/how-to-have-your-benefits-paid" class="govuk-link">how and when your benefits are paid</a>.

spec/components/published_dates_spec.rb

@@ -0,0 +1,112 @@
+RSpec.describe "PublishedDates", type: :view do
+  def component_name
+    "published_dates"
+  end
+
+  it "renders nothing when no dates are provided" do
+    render_component({})
+    expect(rendered).to be_empty
+  end
+
+  it "renders published date" do
+    render_component(published: "1st November 2000")
+    expect(rendered).to have_css(".app-c-published-dates", text: "Published 1st November 2000")
+  end
+
+  it "renders published date and last updated date" do
+    render_component(published: "1st November 2000", last_updated: "15th July 2015")
+    expect(rendered).to have_css(".app-c-published-dates",
+                                 text: "Published 1st November 2000
+    Last updated 15th July 2015")
+  end
+
+  it "links to full page history" do
+    render_component(published: "1st November 2000", last_updated: "15th July 2015", link_to_history: true)
+    expect(rendered).to have_css(".app-c-published-dates a[href=\"#history\"]")
+  end
+
+  it "renders full page history" do
+    render_component(
+      published: "1st November 2000",
+      last_updated: "15th July 2015",
+      history: [display_time: "23 August 2013", note: "Updated with new data"],
+    )
+    expect(rendered).to have_css(".app-c-published-dates__change-history#full-history")
+    expect(rendered).to have_css(".app-c-published-dates--history .app-c-published-dates__change-date", text: "23 August 2013")
+  end
+
+  it "strips leading and trailing whitespace from note text" do
+    render_component(
+      published: "1st November 2000",
+      last_updated: "15th July 2015",
+      history: [display_time: "23 August 2013", note: "Updated with new data"],
+    )
+    expect(rendered).to have_css(".app-c-published-dates__change-history#full-history")
+    expect(rendered).to have_css(".app-c-published-dates--history .app-c-published-dates__change-note", text: /^\S/)
+  end
+
+  it "only adds history id when passed page history" do
+    render_component(published: "1st November 2000")
+    expect(rendered).not_to have_css("#full-publication-update-history", visible: false)
+
+    render_component(
+      published: "1st November 2000",
+      last_updated: "15th July 2015",
+      history: [display_time: "23 August 2013", note: "Updated with new data"],
+    )
+    expect(rendered).to have_css("#full-publication-update-history")
+  end
+
+  it "full page history is hidden on page load" do
+    render_component(
+      published: "1st November 2000",
+      last_updated: "15th July 2015",
+      history: [display_time: "23 August 2013", note: "Updated with new data"],
+    )
+    expect(rendered).to have_css(".app-c-published-dates__change-history.js-hidden")
+  end
+
+  it "renders link to full page history if history is provided" do
+    render_component(
+      published: "1st November 2000",
+      last_updated: "15th July 2015",
+      history: [display_time: "23 August 2013", note: "Updated with new data"],
+    )
+    expect(rendered).to have_css(".app-c-published-dates a[href=\"#full-history\"]")
+  end
+
+  it "includes data attributes for toggle behaviour" do
+    render_component(
+      published: "1st November 2000",
+      last_updated: "15th July 2015",
+      history: [display_time: "23 August 2013", note: "Updated with new data"],
+    )
+
+    expect(rendered).to have_css(".app-c-published-dates--history[data-module='gem-toggle']")
+    expect(rendered).to have_css(".app-c-published-dates--history a[href='#full-history'][data-controls='full-history']")
+    expect(rendered).to have_css(".app-c-published-dates--history a[href='#full-history'][data-expanded='false']")
+  end
+
+  it "applies a custom margin-bottom class if margin_bottom is specified" do
+    render_component(published: "1st November 2000", margin_bottom: 5)
+    expect(rendered).to have_css('.app-c-published-dates.govuk-\!-margin-bottom-5')
+  end
+
+  it "accordion has GA4 tracking" do
+    render_component(
+      published: "1st November 2000",
+      last_updated: "15th July 2015",
+      history: [display_time: "23 August 2013", note: "Updated with new data"],
+    )
+
+    expected_ga4_json = {
+      "event_name": "select_content",
+      "type": "content history",
+      "section": "Footer",
+    }.to_json
+
+    expect(rendered).to have_css("a[data-module='ga4-event-tracker']")
+    expect(rendered).to have_css("a[data-ga4-expandable='']")
+    expect(rendered).to have_css("a[data-ga4-event='#{expected_ga4_json}']")
+  end
+end