Add NotificationBanner component

apps/govuk-docs/src/common/pages/components.tsx

@@ -22,6 +22,7 @@ const mainStories = [
   require('../../../../../components/footer/spec/Footer.stories.mdx'),
   require('../../../../../components/header/spec/Header.stories.mdx'),
   require('../../../../../components/inset-text/spec/InsetText.stories.mdx'),
+  require('../../../../../components/notification-banner/spec/NotificationBanner.stories.mdx'),
   require('../../../../../components/pagination/spec/Pagination.stories.mdx'),
   require('../../../../../components/panel/spec/Panel.stories.mdx'),
   require('../../../../../components/phase-banner/spec/PhaseBanner.stories.mdx'),

components/notification-banner/.gitignore

@@ -0,0 +1,5 @@
+dist/
+node_modules/
+package-lock.json
+pnpm-lock.yaml
+tsconfig.tsbuildinfo

components/notification-banner/README.md

@@ -0,0 +1,70 @@
+NotGovUK - Notification Banner
+==============================
+
+A component to tell the user about something they need to know about, but that’s not directly related to the page content.
+
+
+Using this package
+------------------
+
+First install the package into your project:
+
+```shell
+npm install -S @not-govuk/notification-banner
+```
+
+Then use it in your code as follows:
+
+```js
+import React, { createElement as h } from 'react';
+import NotificationBanner from '@not-govuk/notification-banner';
+
+export const MyComponent = props => (
+  <NotificationBanner>
+    <p class="govuk-notification-banner__heading">
+      You have 7 days left to send your application.
+      <a class="govuk-notification-banner__link" href="#">View application</a>.
+    </p>
+  </NotificationBanner>
+);
+
+export default MyComponent;
+```
+
+
+Working on this package
+-----------------------
+
+Before working on this package you must install its dependencies using
+the following command:
+
+```shell
+pnpm install
+```
+
+
+### Testing
+
+Run the unit tests.
+
+```shell
+npm test
+```
+
+
+### Building
+
+Build the package by compiling the TypeScript source code.
+
+```shell
+npm run build
+```
+
+
+### Clean-up
+
+Remove any previously built files.
+
+```shell
+npm run clean
+```

components/notification-banner/assets/NotificationBanner.scss

@@ -0,0 +1,26 @@
+@import "@not-govuk/sass-base";
+@import "govuk-frontend/govuk/components/notification-banner";
+
+.govuk-notification-banner {
+  &__content {
+    & .heading,
+    & .govuk-heading,
+    & h2 {
+      @extend .govuk-notification-banner__title;
+    }
+  }
+
+  &__content {
+    & .heading,
+    & .govuk-heading,
+    & h3 {
+      @extend .govuk-notification-banner__heading;
+    }
+
+    & .link,
+    & .govuk-link,
+    & a {
+      @extend .govuk-notification-banner__link;
+    }
+  }
+}

components/notification-banner/jest.config.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const baseConfig = require('../../jest.config.base');
+
+const config = {
+  ...baseConfig,
+  collectCoverageFrom: [
+    '<rootDir>/src/**.{ts,tsx}',
+  ],
+  testMatch: [
+    '<rootDir>/spec/**.{ts,tsx}'
+  ]
+};
+
+module.exports = config;

components/notification-banner/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@not-govuk/notification-banner",
+  "version": "0.7.2",
+  "description": "A component to tell the user about something they need to know about, but that’s not directly related to the page content.",
+  "main": "src/NotificationBanner.tsx",
+  "sass": "assets/NotificationBanner.scss",
+  "publishConfig": {
+    "main": "dist/NotificationBanner.js",
+    "typings": "dist/NotificationBanner.d.ts"
+  },
+  "files": [
+    "/assets",
+    "/dist"
+  ],
+  "scripts": {
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "prepublishOnly": "npm run clean && npm run build",
+    "build": "tsc",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "author": "Daniel A.C. Martin <npm@daniel-martin.co.uk> (http://daniel-martin.co.uk/)",
+  "license": "MIT",
+  "keywords": [
+    "react-components"
+  ],
+  "dependencies": {
+    "@not-govuk/component-helpers": "workspace:^0.7.2",
+    "@not-govuk/sass-base": "workspace:^0.7.2",
+    "govuk-frontend": "4.6.0"
+  },
+  "peerDependencies": {
+    "@not-govuk/docs-components": "^0.7.2",
+    "@storybook/addon-docs": "^6.4.0",
+    "react": "^16.9.55"
+  },
+  "peerDependenciesMeta": {
+    "@not-govuk/docs-components": {
+      "optional": true
+    },
+    "@storybook/addon-docs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mdx-js/react": "1.6.22",
+    "@not-govuk/component-test-helpers": "workspace:^0.7.2",
+    "@not-govuk/tag": "workspace:^0.7.2",
+    "@types/react": "16.14.32",
+    "jest": "29.2.2",
+    "jest-environment-jsdom": "29.2.2",
+    "ts-jest": "29.0.3",
+    "typescript": "4.8.4"
+  }
+}

components/notification-banner/spec/NotificationBanner.stories.mdx

@@ -0,0 +1,164 @@
+import { Meta, Preview, Props, Story } from '@storybook/addon-docs';
+import { Tag } from '@not-govuk/tag';
+import { NotificationBanner } from '../src/NotificationBanner';
+import readMe from '../README.md';
+
+<Meta
+  title="Notification banner"
+  component={ NotificationBanner }
+  parameters={ {
+    chromatic: { viewports: [640, 480] },
+    description: 'A component to tell the user about something they need to know about, but that’s not directly related to the page content.',
+    jest: ['NotificationBanner'],
+    notes: readMe
+  } }
+/>
+
+# Notification banner
+
+<div>
+  <Tag>Experimental</Tag>
+  <p>This component is currently experimental because [more research] is needed to validate it.</p>
+</div>
+
+Use a notification banner to tell the user about something they need to know about, but that’s not directly related to the page content.
+
+<Preview withToolbar>
+  <Story name="NotificationBanner">
+    <NotificationBanner>
+      <p class="govuk-notification-banner__heading">
+        You have 7 days left to send your application. <a class="govuk-notification-banner__link" href="#">View application</a>.
+      </p>
+    </NotificationBanner>
+  </Story>
+</Preview>
+
+<Props of={ NotificationBanner } />
+
+
+## When to use this component
+
+A notification banner lets you tell the user about something that’s not directly relevant to the thing they’re trying to do on that page of the service. For example:
+
+- telling the user about a problem that’s affecting the service as a whole (for example, delays in processing applications because of an emergency)
+- telling the user about something that affects them in particular (for example, an approaching deadline they need to meet)
+- telling the user about the outcome of something they’ve just done on a previous page (for example, confirming that an email has been sent)
+
+
+## When not to use this component
+
+Use notification banners sparingly. There’s [evidence that people often miss them], and using them too often is likely to make this problem worse.
+
+If the information is directly relevant to the thing the user is doing on that page, put the information in the main page content instead. Use [inset text] or [warning text] if it needs to stand out.
+
+Do not:
+
+- use a notification banner to tell the user about validation errors - use an [error message] and [error summary] instead
+- show a notification banner and an [error summary] on the same page - just show the error summary
+
+
+## How it works
+
+Position a notification banner immediately before the page `h1`. The notification banner should be the same width as the page’s other content, such as components, headings and body text. For example, if the other content takes up two-thirds of the screen on desktop devices, then the notification banner should also take up two-thirds. [Read about how to lay out pages].
+
+Use `role="region"` and `aria-labelledby="govuk-notification-banner-title"` (with `id="govuk-notification-banner-title"` on `<govuk-notification-banner__title>`) so that screen reader users can navigate to the notification banner.
+
+Avoid showing more than one notification banner on the same page. Instead, combine the messages in a single notification banner. If the messages are too different to combine, only show the highest priority notification banner.
+
+
+### Notification banner headings
+
+You can use `<h3>` headings in the `govuk-notification-banner__content` to help structure your content.
+
+Avoid using headings for single-line notifications that do not need them.
+
+
+## Telling the user about a problem that affects the whole service
+
+Use a ‘neutral’ blue notification banner if the user needs to know about a problem with the service as a whole.
+
+For example:
+
+- in a service that lets the user register or apply for something, they might need to know that it’s taking longer than usual to process applications because of an emergency
+- in an account-type service, the user might need to know that the service will be down for scheduled maintenance
+
+<Preview>
+  <Story name="Standard">
+    <NotificationBanner>There may be a delay in processing your application because of the coronavirus outbreak.</NotificationBanner>
+  </Story>
+</Preview>
+
+If your service is on GOV.UK and it’s affected by an emergency, ask your department’s content team to [request a change to the service start page].
+
+If your service is getting more demand than usual, check that you’ve set up [There is a problem with the service pages] and [Service unavailable pages], and the wording is up to date.
+
+
+## Telling the user about something that’s happening elsewhere
+
+Use a ‘neutral’ notification banner if the user needs to know about something that’s happening elsewhere in the service. For example:
+
+- in a case working system, the user might need to know that there are new cases waiting for their attention
+- in an account-type service, you might need to tell the user that there’s a deadline approaching or that a payment is overdue
+
+<Preview>
+  <Story name="Neutral">
+    <NotificationBanner>
+      <p class="govuk-notification-banner__heading">
+        You have 7 days left to send your application. <a class="govuk-notification-banner__link" href="#">View application</a>.
+      </p>
+    </NotificationBanner>
+  </Story>
+</Preview>
+
+
+## Reacting to something the user has done
+
+You can also use a notification banner to tell the user about the outcome of something they’ve just done - but they have not finished using the service, so it does not make sense to use a [confirmation page].
+
+Using a notification banner is unlikely to be the right approach in a linear service - for example, a service that lets the user register or apply for a thing. For a linear service, it will usually make sense to stick to the [‘one thing per page’ approach]. Do not use a notification banner to tell users that they’ve finished using a linear service. Use a [confirmation page] instead.
+
+Use the green version of the notification banner to confirm that something they’re expecting to happen has happened.
+
+<Preview>
+  <Story name="Success">
+    <NotificationBanner type="success">
+      <h3 class="govuk-notification-banner__heading">
+        Training outcome recorded and trainee withdrawn
+      </h3>
+      <p class="govuk-body">Contact <a class="govuk-notification-banner__link" href="#">example@department.gov.uk</a> if you think there’s a problem.</p>
+    </NotificationBanner>
+  </Story>
+</Preview>
+
+Since you’re using the notification banner to tell the user about the outcome of something they’ve just done, add `role="alert"` so focus shifts to the notification banner on page load.
+
+Remove a green notification banner when the user moves to a new page.
+
+To make the green version of the notification banner accessible:
+
+- use headings like ‘Success’ - so that you’re [not relying on colour alone to convey meaning])
+- use the same heading for green notification banners within the same service - so that you’re [identifying components that work in the same way consistently]
+
+
+<h2 id="research-on-this-component">Research on this component</h2>
+
+We need more research to understand:
+
+- how common it is for users to miss important information in notification banners (including users of assistive technology, who might skip straight to the `h1`)
+- whether it’s sometimes helpful to allow users to dismiss notifications, and how to do this
+
+
+[more research]: #research-on-this-component
+[evidence that people often miss them]: https://www.nngroup.com/articles/banner-blindness-old-and-new-findings/
+[inset text]: https://design-system.service.gov.uk/components/inset-text/
+[warning text]: https://design-system.service.gov.uk/components/warning-text/
+[error message]: https://design-system.service.gov.uk/components/error-message/
+[error summary]: https://design-system.service.gov.uk/components/error-summary/
+[Read about how to lay out pages]: https://design-system.service.gov.uk/styles/layout/
+[request a change to the service start page]: https://www.gov.uk/guidance/contact-the-government-digital-service/request-a-thing#change-govuk-content
+[There is a problem with the service pages]: https://design-system.service.gov.uk/patterns/problem-with-the-service-pages/
+[Service unavailable pages]: https://design-system.service.gov.uk/patterns/service-unavailable-pages/
+[confirmation page]: https://design-system.service.gov.uk/patterns/confirmation-pages/
+[‘one thing per page’ approach]: https://www.gov.uk/service-manual/design/form-structure
+[not relying on colour alone to convey meaning]: https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html
+[identifying components that work in the same way consistently]: https://www.w3.org/WAI/WCAG21/Understanding/consistent-identification