Add Feedback component

CHANGELOG.md

@@ -6,6 +6,12 @@ For advice on how to use these release notes, see [our guidance on staying up to
 
 ### New features
 
+#### Use the Feedback component to collect feedback from users on your service
+
+We've added the [Feedback component](https://design-system.service.gov.uk/components/feedback/) to help services collect feedback from their users throughout their service.
+
+This was added in [pull request #7232: Add Feedback component](https://github.com/alphagov/govuk-frontend/pull/7232).
+
 #### You can now pass `day`, `month`, `year`, `error` and `values` options to the Date input component
 
 We've updated the Date input component to add the following Nunjucks options:

packages/govuk-frontend-review/src/views/examples/translated/index.njk

@@ -12,6 +12,7 @@
 {% from "govuk/components/error-message/macro.njk" import govukErrorMessage %}
 {% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}
 {% from "govuk/components/exit-this-page/macro.njk" import govukExitThisPage %}
+{% from "govuk/components/feedback/macro.njk" import govukFeedback %}
 {% from "govuk/components/file-upload/macro.njk" import govukFileUpload %}
 {% from "govuk/components/footer/macro.njk" import govukFooter %}
 {% from "govuk/components/header/macro.njk" import govukHeader %}
@@ -332,6 +333,14 @@
     ]
   }) }}
 
+  {% call govukFeedback({
+    titleText: "Helpwch ni i wella'r gwasanaeth hwn"
+  }) %}
+    <p class="govuk-body">
+      Dywedwch wrthym am eich profiad o ddefnyddio'r gwasanaeth hwn. <a href="#" class="govuk-link">Rhowch eich adborth i ni</a>
+    </p>
+  {% endcall %}
+
   {{ govukFileUpload({
     id: "file-upload-1",
     name: "file-upload-1",

packages/govuk-frontend-review/src/views/full-page-examples/have-you-changed-your-name/confirm.njk

@@ -1,6 +1,7 @@
 {% extends "layouts/full-page-example.njk" %}
 
 {% from "govuk/components/panel/macro.njk" import govukPanel %}
+{% from "govuk/components/feedback/macro.njk" import govukFeedback %}
 
 {% set pageTitle = "Thank you for confirming if you have changed your name" %}
 {% block pageTitle %}{{ pageTitle }} - GOV.UK{% endblock %}
@@ -14,3 +15,13 @@
     </div>
   </div>
 {% endblock %}
+
+{% block footerStart %}
+  {% call govukFeedback({
+    titleText: "Help us improve this service"
+  }) %}
+    <p class="govuk-body">
+      Tell us about your experience using this service. <a href="#" class="govuk-link">Give us your feedback</a>
+    </p>
+  {% endcall %}
+{% endblock %}

packages/govuk-frontend-review/src/views/full-page-examples/have-you-changed-your-name/index.njk

@@ -16,6 +16,7 @@ scenario: |
 {% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}
 {% from "govuk/components/radios/macro.njk" import govukRadios %}
 {% from "govuk/components/button/macro.njk" import govukButton %}
+{% from "govuk/components/feedback/macro.njk" import govukFeedback %}
 
 {% set pageTitle = example.title %}
 {% block pageTitle %}{{ "Error: " if errorSummary | length }}{{ pageTitle }} - GOV.UK{% endblock %}
@@ -70,3 +71,13 @@ scenario: |
   </form>
 
 {% endblock %}
+
+{% block footerStart %}
+  {% call govukFeedback({
+    titleText: "Help us improve this service"
+  }) %}
+    <p class="govuk-body">
+      Tell us about your experience using this service. <a href="#" class="govuk-link">Give us your feedback</a>
+    </p>
+  {% endcall %}
+{% endblock %}

packages/govuk-frontend/src/govuk-prototype-kit/govuk-prototype-kit.config.unit.test.mjs

@@ -92,6 +92,10 @@ describe('GOV.UK Prototype Kit config', () => {
           importFrom: 'govuk/components/exit-this-page/macro.njk',
           macroName: 'govukExitThisPage'
         },
+        {
+          importFrom: 'govuk/components/feedback/macro.njk',
+          macroName: 'govukFeedback'
+        },
         {
           importFrom: 'govuk/components/fieldset/macro.njk',
           macroName: 'govukFieldset'

packages/govuk-frontend/src/govuk/components/_index.import.scss

@@ -10,6 +10,7 @@
 @import "error-message";
 @import "error-summary";
 @import "exit-this-page";
+@import "feedback";
 @import "fieldset";
 @import "file-upload";
 @import "footer";

packages/govuk-frontend/src/govuk/components/_index.scss

@@ -10,6 +10,7 @@
 @use "error-message";
 @use "error-summary";
 @use "exit-this-page";
+@use "feedback";
 @use "fieldset";
 @use "file-upload";
 @use "footer";

packages/govuk-frontend/src/govuk/components/feedback/README.md

@@ -0,0 +1,15 @@
+# Feedback
+
+## Installation
+
+See the [main README quick start guide](https://github.com/alphagov/govuk-frontend#quick-start) for how to install this component.
+
+## Guidance and Examples
+
+Find out when to use the Feedback component in your service in the [GOV.UK Design System](https://design-system.service.gov.uk/components/feedback).
+
+## Component options
+
+Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
+
+See [options table](https://design-system.service.gov.uk/components/feedback/#options-feedback-example) for details.

packages/govuk-frontend/src/govuk/components/feedback/_feedback.import.scss

@@ -0,0 +1,5 @@
+@use "../../settings/warnings--internal";
+
+@include warnings--internal.component-scss-file-warning("feedback");
+
+@import "index";

packages/govuk-frontend/src/govuk/components/feedback/_index.import.scss

@@ -0,0 +1,7 @@
+@use "mixin";
+
+@import "../../base";
+
+@include govuk-exports("govuk/component/feedback") {
+  @include mixin.styles;
+}

packages/govuk-frontend/src/govuk/components/feedback/_index.scss

@@ -0,0 +1,4 @@
+@use "../../custom-properties";
+@use "mixin";
+
+@include mixin.styles;

packages/govuk-frontend/src/govuk/components/feedback/_mixin.scss

@@ -0,0 +1,42 @@
+@use "../../base";
+
+/// @access private
+@mixin styles {
+  .govuk-feedback {
+    box-sizing: border-box;
+    // Tie left/right padding to page gutter as it stretches across the whole
+    // screen on smaller screens
+    padding: base.govuk-spacing(4) base.$govuk-gutter-half base.govuk-spacing(5);
+    border-top: 1px solid;
+    border-color: base.govuk-functional-colour("brand");
+    background-color: base.govuk-functional-colour("surface-background");
+
+    @media #{base.govuk-from-breakpoint(tablet)} {
+      padding-right: base.govuk-spacing(4);
+      padding-left: base.govuk-spacing(4);
+    }
+
+    // Override $govuk-width-container's left and right margin as we want Feedback
+    // to go across the whole screen on smaller screens
+    @media #{base.govuk-until-breakpoint(tablet)} {
+      margin-right: 0;
+      margin-left: 0;
+    }
+  }
+
+  .govuk-feedback__title {
+    @include base.govuk-font($size: 24, $weight: bold);
+    margin-top: 0;
+    color: base.govuk-functional-colour(text);
+    @include base.govuk-responsive-margin(1, "bottom");
+  }
+
+  // Removes the bottom margin from the final child element eg: a paragraph
+  //
+  // Feedback body doesn't have any opinions about typography. Instead we defer
+  // to users to use typography classes in their input, or apply a `govuk-body`
+  // paragraph for if users pass `text`.
+  .govuk-feedback__body > :last-child {
+    margin-bottom: 0;
+  }
+}

packages/govuk-frontend/src/govuk/components/feedback/accessibility.puppeteer.test.mjs

@@ -0,0 +1,28 @@
+import { axe, render } from '@govuk-frontend/helpers/puppeteer'
+import { getExamples } from '@govuk-frontend/lib/components'
+
+describe('/components/feedback', () => {
+  let axeRules
+
+  beforeAll(() => {
+    axeRules = {
+      /**
+       * Ignore 'Element has insufficient color contrast' for WCAG Level AAA
+       *
+       * Affects links on 'surface background' functional colour
+       */
+      'color-contrast-enhanced': { enabled: false }
+    }
+  })
+
+  describe('component examples', () => {
+    it('passes accessibility tests', async () => {
+      const examples = await getExamples('feedback')
+
+      for (const exampleName in examples) {
+        await render(page, 'feedback', examples[exampleName])
+        await expect(axe(page, axeRules)).resolves.toHaveNoViolations()
+      }
+    }, 120000)
+  })
+})

packages/govuk-frontend/src/govuk/components/feedback/feedback.yaml

@@ -0,0 +1,95 @@
+params:
+  - name: titleText
+    type: string
+    required: true
+    description: Text to use within the title of the Feedback component. If `titleHtml` is provided, the `titleText` option will be ignored.
+  - name: titleHtml
+    type: string
+    required: true
+    description: HTML to use within the title of the Feedback component. If `titleHtml` is provided, the `titleText` option will be ignored.
+  - name: headingLevel
+    type: integer
+    required: false
+    description: Heading level, from `1` to `6`. Default is `2`.
+  - name: text
+    type: string
+    required: true
+    description: Text to use within the Feedback component content. If `html` is provided, the `text` option will be ignored.
+  - name: html
+    type: string
+    required: true
+    description: HTML to use within the Feedback component content. If `html` is provided, the `text` option will be ignored.
+  - name: caller
+    type: nunjucks-block
+    required: false
+    description: Not strictly a parameter but a [Nunjucks code convention](https://mozilla.github.io/nunjucks/templating.html#call). Using a `call` block lets you call a macro with all the text inside the tag. This is helpful if you want to pass a lot of content into a macro. To use it, you'll need to wrap the entire Feedback component in a `call` block.
+  - name: classes
+    type: string
+    required: false
+    description: Classes to add to the Feedback component container.
+  - name: attributes
+    type: object
+    required: false
+    description: HTML attributes (for example, data attributes) to add to the Feedback component container.
+
+examples:
+  - name: default
+    screenshot: true
+    options:
+      titleText: Help us improve this service
+      html: |
+        <p class="govuk-body">Tell us about your experience using this service. <a href="#" class="govuk-link">Give us your feedback</a></p>
+
+  - name: silly example
+    description: In reality we'd recommend users only use the default example but this is to illustrate if a service team decides they want to add a lot of content
+    options:
+      titleText: Help us improve this service
+      html: |
+        <p class="govuk-body">Tell us about your experience using this service.</p>
+        <p class="govuk-body">Click this cool link to <a href="#" class="govuk-link">give us your feedback</a>.</p>
+        <p class="govuk-body">There's another paragraph here.</p>
+        <ul class="govuk-list govuk-list--bullet">
+          <li>There is also a list</li>
+          <li>With items in</li>
+          <li>How strange!</li>
+        </ul>
+
+  # Hidden examples are not shown in the review app, but are used for tests and HTML fixtures
+  - name: html in title
+    hidden: true
+    options:
+      titleHtml: Help us improve this <em>cool</em> service
+      html: |
+        <p class="govuk-body">Tell us about your experience using this service. <a href="#" class="govuk-link">Give us your feedback</a></p>
+
+  - name: custom heading level
+    hidden: true
+    options:
+      titleText: Help us improve this service
+      headingLevel: 3
+      html: |
+        <p class="govuk-body">Tell us about your experience using this service. <a href="#" class="govuk-link">Give us your feedback</a></p>
+
+  - name: html in text options
+    hidden: true
+    options:
+      titleText: Help us improve this <em>cool</em> service
+      text: Tell us about your experience using this <em>cool</em> service
+
+  - name: classes
+    hidden: true
+    options:
+      titleText: Help us improve this service
+      html: |
+        <p class="govuk-body">Tell us about your experience using this service. <a href="#" class="govuk-link">Give us your feedback</a></p>
+      classes: my-first-class my-second-class
+
+  - name: attributes
+    hidden: true
+    options:
+      titleText: Help us improve this service
+      html: |
+        <p class="govuk-body">Tell us about your experience using this service. <a href="#" class="govuk-link">Give us your feedback</a></p>
+      attributes:
+        first-attribute: first
+        second-attribute: second

packages/govuk-frontend/src/govuk/components/feedback/macro.njk

@@ -0,0 +1,3 @@
+{% macro govukFeedback(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

packages/govuk-frontend/src/govuk/components/feedback/template.njk

@@ -0,0 +1,24 @@
+{% from "../../macros/attributes.njk" import govukAttributes -%}
+
+{% set headingLevel = params.headingLevel if params.headingLevel else 2 -%}
+
+<div class="govuk-feedback govuk-width-container {%- if params.classes %} {{ params.classes }}{% endif %}" {{- govukAttributes(params.attributes) }}>
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      <h{{ headingLevel }} class="govuk-feedback__title">
+        {{ params.titleHtml | safe if params.titleHtml else params.titleText }}
+      </h{{ headingLevel }}>
+      {% if caller or params.html or params.text %}
+        <div class="govuk-feedback__body">
+          {% if caller or params.html %}
+            {{ caller() if caller else params.html | safe | trim | indent(4) }}
+          {% elif params.text %}
+            <p class="govuk-body">
+              {{ params.text | trim | indent(6) }}
+            </p>
+          {% endif %}
+        </div>
+    {% endif %}
+    </div>
+  </div>
+</div>