govuk_publishing_components 23.12.2 → 23.15.0

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

@@ -1,16 +1,16 @@
 name: Document list
 description: An ordered list of documents including a document type, when updated and a link.
 body: |
-  Outputs a list to documents, based on an array of document data. This may include:
+  Outputs a list to documents, based on an array of document data. A "document" in this context can be an asset (such as a ODT or other downloadable document) or a web page.
+  
+  The component can display:
 
-  * document title
-  * link to the document
-  * last updated date object
-  * document type
+  * a document title
+  * a link to the document
+  * a last updated date object
+  * a document type
 
   Tracking can be added to the links by supplying optional data attributes for each.
-
-  Documents are presented in an ordered list as the component expects that the ordering of the documents is relevant.
 accessibility_criteria: |
   The component must:
 
@@ -195,6 +195,23 @@ examples:
           public_updated_at: 2017-07-19 15:01:48
           document_type: 'Statistical data set'
         subtext: 'First published during the 1996 Conservative Government'
+  without_top_border_on_list_element:
+    description: Several interfaces across GOV.UK benefit from the semantics of the document list but have their own bespoke designs, sometimes meaning that the visual border element doesn't gel with said interface. Removing it using the below attribute allows for cleaner visual fidelity in this instances.
+    data:
+      remove_top_border: true
+      items:
+      - link:
+          text: 'Department for Education – Statistics at DfE'
+          path: '/government/organisations/department-for-education/about/statistics'
+        metadata:
+          public_updated_at: 2017-07-19 15:01:48
+          document_type: 'Corporate information'
+      - link:
+          text: 'State-funded school inspections and outcomes: management information'
+          path: '/government/organisations/department-for-education/about/statistics'
+        metadata:
+          public_updated_at: 2017-07-19 15:01:48
+          document_type: 'Statistical data set'
   highlighted_result:
     description: Highlight one or more of the items in the list. This is used on finders to provide a 'top result' for a search. The `highlight_text` parameter is optional.
     data:
@@ -280,3 +297,11 @@ examples:
           document_type: 'Data tryloywder'
           locale:
             document_type: 'cy'
+  with_full_size_description_text:
+    data:
+      items:
+      - link:
+          text: 'Become an apprentice'
+          path: '/become-an-apprentice'
+          description: 'Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.'
+          full_size_description: true

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

@@ -60,6 +60,38 @@ examples:
       - text: News and communications
         href: "item-6"
         active: true
+  with_custom_navigation_aria_label:
+    description: The navigation has `aria-label="Top level"` by default. This option is here for when the `aria-label` needs to be more descriptive than that.
+    data:
+      search_left: true
+      navigation_aria_label: "Departments and policy"
+      navigation_items:
+      - text: Departments
+        href: "item-1"
+      - text: Worldwide
+        href: "item-2"
+      - text: How government works
+        href: "item-3"
+      - text: Get involved
+        href: "item-4"
+      - text: Consultations
+        href: "item-4"
+      - text: Statistics
+        href: "item-5"
+      - text: News and communications
+        href: "item-6"
+        active: true
+  with_navigation_link_data_attributes:
+    description: Supports adding data attributes i.e for tracking
+    data:
+      navigation_items:
+      - text: Departments
+        href: "item-1"
+        data:
+          module: "a custom attribute"
+          something_else: "some other custom attribute"
+      - text: Worldwide
+        href: "item-2"
   full_width:
     description: |
       This is difficult to preview because the preview windows are constrained, but the header will stretch to the size of its container.

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

@@ -4,11 +4,43 @@ body: |
   This takes a content-store links hash like object which it can then turn into
   the correct analytics identifier metadata tags.
 
-  The code which reads the meta tags can be found <a href="https://github.com/alphagov/static/blob/master/app/assets/javascripts/analytics/static-analytics.js#L76-L96">in static-analytics.js</a>.
+  These are additionally used by the <a href="https://github.com/alphagov/govuk-browser-extension">GOV.UK browser extension</a> to provide details about a given page. 
+
+  The code which reads the meta tags can be found <a href="https://github.com/alphagov/govuk_publishing_components/blob/master/app/assets/javascripts/govuk_publishing_components/analytics/custom-dimensions.js">in custom-dimensions.js</a>.
 accessibility_criteria: |
   The analytics meta tags component should not be visible to any users.
 display_html: true
 examples:
+  with_core_tags:
+    data:
+      content_item:
+        document_type: "html_publication"
+        publishing_app: "whitehall"
+        schema_name: "html_publication"
+        content_id: "00000000-0000-0000-0000-00000000000"
+        navigation_page_type: "Taxon Page"
+        section: "business tax"
+        withdrawn_notice: true
+  with_content_history_tags:
+    description: |
+      The tags in this object will generate the `content-has-history` tag, set to true. This tag is triggered when either, within `content_item`:
+      
+      1. `public_updated_at` and `first_public_at` within `details` are both present and they aren't the same value
+      2. `change_history` within `details` is present and it has a value of more than 1
+
+      See below example for specific details.
+    data:
+      content_item:
+        public_updated_at: "2021-01-15T12:30:45.000+00:00"
+        details:
+          first_public_at: "2020-11-03T09:15:00.000+00:00"
+          change_history: "5"
+  with_date_and_postcode_stripping_for_static_analytics:
+    data:
+      content_item:
+      local_assigns:
+        strip_dates_pii: true
+        strip_postcodes_pii: true
   with_organisations:
     data:
       content_item:
@@ -24,3 +56,69 @@ examples:
         links:
           world_locations:
           - analytics_identifier: WL3
+  with_political_tags:
+    data:
+      content_item:
+        details:
+          political: true
+          government:
+            current: true
+            slug: "2010-to-2015-conservative-and-liberal-democrat-coalition-government"
+  with_historic_political_tags:
+    data:
+      content_item:
+        details:
+          political: true
+          government:
+            current: false
+            slug: "2010-to-2015-conservative-and-liberal-democrat-coalition-government"
+  with_non-political_tags:
+    data:
+      content_item:
+        details:
+          political: false
+          government:
+            slug: "2010-to-2015-conservative-and-liberal-democrat-coalition-government"
+  with_taxonomy_added_via_document_type:
+    description: |
+      You can trigger taxonomy tag rendering by either including a `document_type` attributes of "taxon" or including the `parent_taxons` or `taxons` attributes under the `links` attribute.
+    data:
+      content_item:
+        content_id: "00000000-0000-0000-0000-000000000000"
+        document_type: "taxon"
+        base_path: "/example-of-taxons"
+  with_taxonomy_added_via_links:
+    data:
+      content_item:
+        links:
+          taxons:
+            - content_id: "11111111-1111-1111-1111-111111111111"
+              document_type: "taxon"
+              base_path: "/disabilities-benefits"
+            - content_id: "22222222-2222-2222-2222-222222222222"
+              document_type: "taxon"
+              base_path: "/childcare-parenting/childrens-social-care-providers"
+              links:
+                parent_taxons:
+                  - content_id: "33333333-3333-3333-3333-333333333333"
+                    document_type: "taxon"
+                    base_path: "/childcare-parenting"
+  with_multiple_step_by_step_tags:
+    data:
+      content_item:
+        links:
+          part_of_step_navs:
+            - content_id: "00000000-0000-0000-0000-000000000000"
+            - content_id: "11111111-1111-1111-1111-111111111111"
+  with_primary_step_by_step_tag:
+    data:
+      content_item:
+        links:
+          part_of_step_navs:
+            - content_id: "00000000-0000-0000-0000-000000000000"
+  with_secondary_step_by_step_tag:
+    data:
+      content_item:
+        links:
+          secondary_to_step_navs:
+            - content_id: "22222222-2222-2222-2222-222222222222"

data/app/views/govuk_publishing_components/components/docs/subscription-links.yml

@@ -1,3 +1,6 @@
+# DO NOT MAKE CHANGES TO THIS FILE
+# It is a temporary copy of subscription_links.yml and will be deleted shortly
+
 name: Subscription links
 description: Links to ‘Get emails’ and ‘Subscribe to feed’
 body: |

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

@@ -0,0 +1,100 @@
+name: Subscription links
+description: Links to ‘Get emails’ and ‘Subscribe to feed’
+body: |
+  <strong>NOTE: This component includes a h2 heading by default but can be suppressed by using `hide_heading` option (see below)<strong>
+accessibility_criteria: |
+  Icons in subscription links must be presentational and ignored by screen readers.
+
+  Toggle elements in the component must:
+
+  - be usable with a keyboard
+  - be usable with touch
+  - be recognised by screen readers as a button
+  - announce to screen readers whether they are expanded or collapsed
+  - show hidden elements by default when Javascript is disabled
+shared_accessibility_criteria:
+  - link
+examples:
+  default:
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      feed_link: '/foreign-travel-advice/singapore.atom'
+  with_margin:
+    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). It defaults to having no margin bottom, although some margin is supplied by the links themselves (so that when they stack on mobile there is space between them).
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      feed_link: '/foreign-travel-advice/singapore.atom'
+      margin_bottom: 9
+  with_only_email_signup_link:
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+  with_only_feed_link:
+    data:
+      feed_link: '/foreign-travel-advice/singapore.atom'
+  with_custom_text:
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      email_signup_link_text: 'Get notifications'
+      feed_link: '/foreign-travel-advice/singapore.atom'
+      feed_link_text: 'View feed'
+  with_copyable_feed_link:
+    description: |
+      This option changes the feed link to a toggle control, which opens a hidden element containing an input prepopulated with the value passed to the component, usually a URL to an atom feed. This uses the [form input](/component-guide/input) component.
+
+      Note that this option overrides the feed_link option, so if both are passed feed_link is ignored. Note that a value for email_signup_link can also be passed as normal.
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      feed_link_box_value: 'https://www.gov.uk/government/organisations/attorney-generals-office.atom'
+  with_branding:
+    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/master/docs/component_branding.md) can be added to the component as shown.
+    data:
+      brand: 'attorney-generals-office'
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      feed_link: '/foreign-travel-advice/singapore.atom'
+  with_tracking:
+    description: Data attributes can be passed for each link as shown.
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      email_signup_link_data_attributes: {
+        track_category: 'email_link_category',
+        track_action: 1.1,
+        track_label: 'email_link_label',
+        track_options: {
+          dimension28: 1,
+          dimension29: 'dimension29EmailLink'
+        }
+      }
+      feed_link_box_value: 'https://www.gov.uk/government/organisations/attorney-generals-office.atom'
+      feed_link_data_attributes: {
+        track_category: 'feed_link_category',
+        track_action: 1.2,
+        track_label: 'feed_link_label',
+        track_options: {
+          dimension28: 7,
+          dimension29: 'dimension29feedLink'
+        }
+      }
+  as_small_form:
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      feed_link: '/foreign-travel-advice/singapore.atom'
+      small_form: true
+  without_heading:
+    description: |
+      By default the component includes an h2 heading. The component could be used anywhere on the page and could mean that it produces invalid markup or make the site unaccessible.
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      feed_link: '/foreign-travel-advice/singapore.atom'
+      hide_heading: true
+  with_a_different_language:
+    data:
+      email_signup_link: '/foreign-travel-advice/singapore/email-signup'
+      email_signup_link_text: 'Recevez des notifications'
+      email_signup_link_text_locale: 'fr'
+      feed_link: '/foreign-travel-advice/singapore.atom'
+      feed_link_text: 'Flux RSS'
+      feed_link_text_locale: 'fr'
+    description: |
+      The component is used on translated pages that don't have a translation for the text strings. This means that it could display the fallback English string if the translate method can't find an appropriate translation. This makes sure that the `lang` can be set to ensure that browsers understand which parts of the page are in each language.
+
+      The `lang` attribute **must** be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is `en` or `eng`, Korean is `ko` or `kor` - but if in doubt please check.

data/app/views/govuk_publishing_components/components/docs/translation-nav.yml

@@ -1,3 +1,6 @@
+# DO NOT MAKE CHANGES TO THIS FILE
+# It is a temporary copy of translation_nav.yml and will be deleted shortly
+
 name: Translation navigation
 description: A list of links to available translations
 body: The active property indicates the current language.
@@ -134,4 +137,3 @@ examples:
             dimension29: 'dimension29Welsh'
     context:
       dark_background: true
-

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

@@ -0,0 +1,137 @@
+name: Translation navigation
+description: A list of links to available translations
+body: The active property indicates the current language.
+accessibility_criteria: |
+  The component must:
+
+  - be [a landmark with a navigation role](https://accessibility.blog.gov.uk/2016/05/27/using-navigation-landmarks/)
+  - have an accessible name in the current language, eg "Translations"
+
+  The translation links must:
+
+  - [identify the language of the text](https://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-other-lang-id.html#meaning-other-lang-id-examples-head)
+
+    [Watch a screen reader pronounce text differently based on lang attribute](https://bit.ly/screenreaderpronunciation)
+shared_accessibility_criteria:
+  - link
+examples:
+  default:
+    data:
+      translations:
+      - locale: 'en'
+        base_path: '/en'
+        text: 'English'
+        active: true
+      - locale: 'hi'
+        base_path: '/hi'
+        text: 'हिंदी'
+  multiple_translations:
+    data:
+      translations:
+      - locale: 'en'
+        base_path: '/en'
+        text: 'English'
+        active: true
+      - locale: 'fr'
+        base_path: '/fr'
+        text: 'Français'
+      - locale: 'hi'
+        base_path: '/hi'
+        text: 'हिंदी'
+      - locale: 'ja'
+        base_path: '/ja'
+        text: '日本語'
+      - locale: 'ur'
+        base_path: '/ur'
+        text: 'اردو'
+      - locale: 'zh'
+        base_path: '/zh'
+        text: '中文'
+  right_to_left:
+    data:
+      translations:
+        - locale: 'en'
+          base_path: '/en'
+          text: 'English'
+        - locale: 'ar'
+          base_path: '/ar'
+          text: 'العربية'
+          active: true
+    context:
+      right_to_left: true
+  with_branding:
+    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/master/docs/component_branding.md) can be added to the component as shown.
+    data:
+      brand: 'wales-office'
+      translations:
+      - locale: 'en'
+        base_path: '/en'
+        text: 'English'
+        active: true
+      - locale: 'cy'
+        base_path: '/cy'
+        text: 'Cymraeg'
+  with_no_top_margin:
+    data:
+      no_margin_top: true
+      translations:
+      - locale: 'en'
+        base_path: '/en'
+        text: 'English'
+        active: true
+      - locale: 'cy'
+        base_path: '/cy'
+        text: 'Cymraeg'
+  with_tracking:
+    description: Data attributes can be passed for each link as shown.
+    data:
+      translations:
+      - locale: 'en'
+        base_path: '/en'
+        text: 'English'
+        active: true
+        data_attributes:
+          track_category: 'categoryEnglish'
+          track_action: 1.1
+          track_label: 'labelEnglish'
+          track_options:
+            dimension28: 1
+            dimension29: 'dimension29English'
+      - locale: 'cy'
+        base_path: '/cy'
+        text: 'Cymraeg'
+        data_attributes:
+          track_category: 'categoryWelsh'
+          track_action: 1.2
+          track_label: 'labelWelsh'
+          track_options:
+            dimension28: 1
+            dimension29: 'dimension29Welsh'
+  inverse:
+    data:
+      inverse: true
+      translations:
+      - locale: 'en'
+        base_path: '/en'
+        text: 'English'
+        active: true
+        data_attributes:
+          track_category: 'categoryEnglish'
+          track_action: 1.1
+          track_label: 'labelEnglish'
+          track_options:
+            dimension28: 1
+            dimension29: 'dimension29English'
+      - locale: 'cy'
+        base_path: '/cy'
+        text: 'Cymraeg'
+        data_attributes:
+          track_category: 'categoryWelsh'
+          track_action: 1.2
+          track_label: 'labelWelsh'
+          track_options:
+            dimension28: 1
+            dimension29: 'dimension29Welsh'
+    context:
+      dark_background: true
+