Add ServiceNavigation component

apps/govuk-docs/src/common/stories.ts

@@ -32,6 +32,7 @@ const mainStories = [
   require('../../../../components/phase-banner/spec/PhaseBanner.stories.mdx'),
   require('../../../../components/radios/spec/Radios.stories.mdx'),
   require('../../../../components/select/spec/Select.stories.mdx'),
+  require('../../../../components/service-navigation/spec/ServiceNavigation.stories.mdx'),
   require('../../../../components/skip-link/spec/SkipLink.stories.mdx'),
   require('../../../../components/summary-list/spec/SummaryList.stories.mdx'),
   require('../../../../components/table/spec/Table.stories.mdx'),

components/service-navigation/.gitignore

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

components/service-navigation/README.md

@@ -0,0 +1,78 @@
+NotGovUK - Service Navigation
+=============================
+
+A component to help users understand that they’re using your service and lets them navigate around your service.
+
+
+Using this package
+------------------
+
+First install the package into your project:
+
+```shell
+npm install -S @not-govuk/service-navigation
+```
+
+Then use it in your code as follows:
+
+```js
+import React, { createElement as h } from 'react';
+import ServiceNavigation from '@not-govuk/service-navigation';
+
+export const MyComponent = props => (
+  <ServiceNavigation items={[
+    {
+      href: "/#",
+      text: "Navigation item 1"
+    },
+    {
+      href: "#active",
+      text: "Navigation item 2",
+    },
+    {
+      href: "/#",
+      text: "Navigation item 3"
+    }
+  ]} />
+);
+
+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/service-navigation/assets/ServiceNavigation.scss

@@ -0,0 +1,22 @@
+@import "@not-govuk/sass-base";
+@import "govuk-frontend/dist/govuk/components/service-navigation/index";
+
+.govuk-service-navigation {
+  &__list {
+    &__item {
+      @extend .govuk-service-navigation__item;
+
+      &--active {
+        @extend .govuk-service-navigation__item--active;
+      }
+    }
+
+    &__link {
+      @extend .govuk-service-navigation__link;
+
+      &--active {
+        @extend .govuk-service-navigation__link--active !optional;
+      }
+    }
+  }
+}

components/service-navigation/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/service-navigation/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@not-govuk/service-navigation",
+  "version": "0.15.2",
+  "description": "A component to help users understand that they’re using your service and lets them navigate around your service.",
+  "main": "src/ServiceNavigation.tsx",
+  "sass": "assets/ServiceNavigation.scss",
+  "publishConfig": {
+    "main": "dist/ServiceNavigation.js",
+    "typings": "dist/ServiceNavigation.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 <[email protected]> (http://daniel-martin.co.uk/)",
+  "license": "MIT",
+  "keywords": [
+    "react-components"
+  ],
+  "dependencies": {
+    "@not-govuk/anchor-list": "workspace:^0.15.2",
+    "@not-govuk/component-helpers": "workspace:^0.15.2",
+    "@not-govuk/link": "workspace:^0.15.2",
+    "@not-govuk/sass-base": "workspace:^0.15.2",
+    "@not-govuk/width-container": "workspace:^0.15.2",
+    "govuk-frontend": "5.7.1"
+  },
+  "peerDependencies": {
+    "@not-govuk/docs-components": "^0.15.2",
+    "@storybook/addon-docs": "^6.5.16",
+    "react": "^18.3.1"
+  },
+  "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.15.2",
+    "@not-govuk/header": "workspace:^0.15.2",
+    "@types/react": "18.3.18",
+    "jest": "29.7.0",
+    "jest-environment-jsdom": "29.7.0",
+    "ts-jest": "29.2.5",
+    "typescript": "4.9.5"
+  }
+}

components/service-navigation/spec/ServiceNavigation.stories.mdx

@@ -0,0 +1,131 @@
+import { Fragment } from 'react';
+import { Meta, Preview, Props, Story } from '@storybook/addon-docs';
+import { Header } from '@not-govuk/header';
+import { ServiceNavigation } from '../src/ServiceNavigation';
+import readMe from '../README.md';
+
+<Meta
+  title="Service navigation"
+  component={ ServiceNavigation }
+  parameters={ {
+    chromatic: { viewports: [640, 480] },
+    description: 'A component to help users understand that they’re using your service and lets them navigate around your service.',
+    jest: ['ServiceNavigation'],
+    notes: readMe
+  } }
+/>
+
+# Service navigation
+
+Service navigation helps users understand that they’re using your service and lets them navigate around your service.
+
+<Preview withToolbar>
+  <Story name="ServiceNavigation">
+    <ServiceNavigation items={[
+      {
+        href: "/#",
+        text: "Navigation item 1"
+      },
+      {
+        href: "#active",
+        text: "Navigation item 2",
+      },
+      {
+        href: "/#",
+        text: "Navigation item 3"
+      }
+    ]} />
+  </Story>
+</Preview>
+
+<Props of={ ServiceNavigation } />
+
+
+## When to use this component
+
+Use the Service navigation to help users understand that they’re using your service.
+
+To decide when to use navigation links in your service, see the [Help users to navigate a service pattern].
+
+
+## How it works
+
+Together, the [GOV.UK header component] and Service navigation component ensure users get a consistent experience on GOV.UK.
+
+This also assures users that they’re in the right place to use your service and to understand that GOV.UK functions as one website.
+
+For guidance on how to plan your header and navigation, see the [Help users navigate a service pattern].
+
+
+### Change the blue colour bar under the GOV.UK header to full width
+
+To use the GOV.UK header and Service navigation and make them fit together visually, you’ll need to change the bottom blue border of the GOV.UK header to full width.
+
+Apply a class `govuk-header--full-width-border` to the GOV.UK header.
+
+<Preview>
+  <Story name="With header">
+    <>
+    <Header govUK classModifiers="full-width-border" />
+    <ServiceNavigation items={[
+      {
+        href: "/#",
+        text: "Navigation item 1"
+      },
+      {
+        href: "#active",
+        text: "Navigation item 2",
+      },
+      {
+        href: "/#",
+        text: "Navigation item 3"
+      }
+    ]} />
+    </>
+  </Story>
+</Preview>
+
+
+### Showing your service name only
+
+We recommend that you use the Service navigation component to show your service name, instead of the GOV.UK header, and to start updating existing services.
+
+<Preview>
+  <Story name="Service name">
+    <ServiceNavigation serviceName="Service name" serviceHref="#" />
+  </Story>
+</Preview>
+
+
+### Showing service name and navigation links
+
+Show navigation links to let users navigate to different parts of your service and find useful links and tools.
+
+<Preview>
+  <Story name="Full">
+    <ServiceNavigation
+      serviceName="Service name"
+      serviceHref="#"
+      items={[
+        {
+          href: "/#",
+          text: "Navigation item 1"
+        },
+        {
+          href: "#active",
+          text: "Navigation item 2",
+        },
+        {
+          href: "/#",
+          text: "Navigation item 3"
+        }
+      ]}
+    />
+  </Story>
+</Preview>
+
+See when and how to show navigation links in the [Help users navigate a service pattern].
+
+
+[Help users to navigate a service pattern]: https://design-system.service.gov.uk/patterns/navigate-a-service/
+[GOV.UK header component]: /components?name=Header