@nationalarchives/frontend 0.1.9-prerelease → 0.1.10-prerelease

package/nationalarchives/components/header/header.stories.js

@@ -1,14 +1,14 @@
 import Header from "./template.njk";
-import "./_index.scss";
 import macroOptions from "./macro-options.json";
 
 const argTypes = {
-  strapline: { control: "text" },
+  logo: { control: "object" },
   navigation: { control: "object" },
   colour: {
     control: "radio",
     options: ["black", "yellow", "pink", "orange", "green", "blue"],
   },
+  exit: { control: "object" },
   classes: { control: "text" },
   attributes: { control: "object" },
 };
@@ -24,12 +24,13 @@ export default {
   argTypes,
 };
 
-const Template = ({ strapline, navigation, colour, classes, attributes }) => {
+const Template = ({ logo, navigation, colour, exit, classes, attributes }) => {
   return Header({
     params: {
-      strapline,
+      logo,
       navigation,
       colour,
+      exit,
       classes,
       attributes,
     },
@@ -38,7 +39,10 @@ const Template = ({ strapline, navigation, colour, classes, attributes }) => {
 
 export const Standard = Template.bind({});
 Standard.args = {
-  strapline: "Beta",
+  logo: {
+    strapline: "Beta",
+    href: "#/",
+  },
   navigation: [
     {
       text: "Alpha",
@@ -55,5 +59,10 @@ Standard.args = {
     },
   ],
   colour: "yellow",
+  exit: {
+    text: "Go to the current National Archives website",
+    href: "#",
+    target: "_blank",
+  },
   classes: "tna-header--demo",
 };

package/nationalarchives/components/header/macro-options.json

@@ -1,9 +1,29 @@
 [
   {
-    "name": "strapline",
-    "type": "string",
+    "name": "logo",
+    "type": "object",
     "required": false,
-    "description": ""
+    "description": "",
+    "params": [
+      {
+        "name": "href",
+        "type": "string",
+        "required": false,
+        "description": ""
+      },
+      {
+        "name": "title",
+        "type": "string",
+        "required": false,
+        "description": ""
+      },
+      {
+        "name": "strapline",
+        "type": "string",
+        "required": false,
+        "description": ""
+      }
+    ]
   },
   {
     "name": "navigation",
@@ -37,16 +57,48 @@
       }
     ]
   },
+  {
+    "name": "colour",
+    "type": "string",
+    "required": false,
+    "description": ""
+  },
+  {
+    "name": "exit",
+    "type": "object",
+    "required": false,
+    "description": "",
+    "params": [
+      {
+        "name": "text",
+        "type": "string",
+        "required": true,
+        "description": ""
+      },
+      {
+        "name": "href",
+        "type": "string",
+        "required": true,
+        "description": ""
+      },
+      {
+        "name": "target",
+        "type": "string",
+        "required": false,
+        "description": ""
+      }
+    ]
+  },
   {
     "name": "classes",
     "type": "string",
     "required": false,
-    "description": "Classes to add to the hero."
+    "description": "Classes to add to the header."
   },
   {
     "name": "attributes",
     "type": "object",
     "required": false,
-    "description": "HTML attributes (for example data attributes) to add to the hero."
+    "description": "HTML attributes (for example data attributes) to add to the header."
   }
 ]

package/nationalarchives/components/header/template.njk

@@ -3,10 +3,24 @@
   {%- set classes = classes.concat('tna-header--' + params.colour) -%}
 {%- endif -%}
 <header class="tna-header {{ classes | join(' ') }}" data-module="tna-header" {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+  {%- if params.exit -%}
+  <div class="tna-header__exit">
+    <div class="tna-container">
+      <div class="tna-column tna-column--full">
+        <a href="{{ params.exit.href }}" class="tna-header__exit-link"{%- if params.exit.target -%} target="{{ params.exit.target }}"{%- endif -%}>
+          {{ params.exit.text }}
+          {%- if params.exit.target == "_blank" -%}
+          <span class="tna-header__exit-link-icon"></span>
+          {%- endif -%}
+        </a>
+      </div>
+    </div>
+  </div>
+  {%- endif -%}
   <div class="tna-container tna-header__contents">
     <div class="tna-column tna-header__logo">
-      <a href="#" class="tna-header__logo-link">
-        <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0" y="0" viewBox="0 0 160 160" style="enable-background:new 0 0 160 160;" xml:space="preserve" class="tna-logo">
+      <{%- if params.logo.href -%}a href="{{ params.logo.href }}" class="tna-header__logo-link tna-header__logo-link--href"{%- else -%}span class="tna-header__logo-link"{%- endif -%}>
+        <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0" y="0" viewBox="0 0 160 160" style="enable-background:new 0 0 160 160;" xml:space="preserve" class="tna-logo" width="100" height="100">
           <rect class="tna-logo__background" fill="none" width="160" height="160"/>
           <g class="tna-logo__foreground" fill="#000">
             <path d="M1.9,107.2h156.3V158H1.9V107.2z M1.9,54.5h79.1h77.2v50.8H1.9V54.5z M1.9,1.9h77.2v50.8H1.9V1.9z M80.9,1.9 h77.2v50.8H80.9C80.9,52.7,80.9,1.9,80.9,1.9z M80.9,0H0v52.7v1.9v50.8v1.9v52.7h160v-52.7v-1.9V52.7V0H80.9z"/>
@@ -31,15 +45,13 @@
             <path d="M130.4,136c0,0.2-0.1,0.5-0.1,0.8c0,1.9,0.8,3.7,3.4,3.7c2.1,0,3.3-1.2,3.3-2.9c0-1.6-0.7-2.4-2.2-3l-3.4-1.3c-2.4-0.9-4.2-2.4-4.2-5.7c0-3.5,2.3-6.1,6.6-6.1c5.5,0,6.4,3.6,6.4,5.9c0,0.3,0,0.7-0.1,1.1l-3.4,0.1c0-0.2,0.1-0.5,0.1-0.7c0-1.7-0.6-3.2-3-3.2c-2.1,0-3,1.2-3,2.8c0,1.7,0.9,2.5,2.2,2.9l3.5,1.3c2.6,1,4.3,2.6,4.3,5.8c0,3.6-2.4,6.1-7,6.1c-5.9,0-6.8-3.9-6.8-6.5c0-0.3,0-0.6,0.1-1L130.4,136z"/>
           </g>
         </svg>
-        {%- if params.strapline -%}
-        <span class="tna-header__logo-strapline">{{ params.strapline }}</span>
+        {%- if params.logo.strapline -%}
+        <span class="tna-header__logo-strapline">{{ params.logo.strapline }}</span>
         {%- endif -%}
-      </a>
+      </{%- if params.logo.href -%}a{%- else -%}span{%- endif -%}>
     </div>
     {%- if params.navigation -%}
-    <div class="tna-column tna-column--flex-1- tna-header__navigation-toggle">
-      <!-- POPULATED BY JAVASCRIPT IF ENABLED -->
-    </div>
+    <div class="tna-column tna-column--flex-1- tna-header__navigation-toggle"><!-- POPULATED BY JAVASCRIPT IF ENABLED --></div>
     <nav class="tna-column tna-column--flex-1 tna-column--full-small tna-column--full-tiny tna-header__navigation" aria-label="Main site navigation">
       <ul class="tna-header__navigation-items">
       {%- for item in params.navigation -%}

package/nationalarchives/components/hero/_index.scss

@@ -96,6 +96,7 @@
   }
 
   &__body {
+    margin-top: 1.5rem;
   }
 
   @include media.on-mobile {
@@ -138,9 +139,11 @@
     }
 
     &__heading {
+      color: inherit;
     }
 
     &__body {
+      color: inherit;
     }
   }
 

package/nationalarchives/components/hero/hero.stories.js

@@ -1,5 +1,4 @@
 import Hero from "./template.njk";
-import "./_index.scss";
 import macroOptions from "./macro-options.json";
 import { expect } from "@storybook/jest";
 import { within, userEvent } from "@storybook/testing-library";
@@ -49,7 +48,7 @@ Standard.args = {
   classes: "tna-hero--demo",
 };
 
-Standard.play = async ({ args, canvasElement }) => {
+Standard.play = async ({ args, canvasElement, step }) => {
   const canvas = within(canvasElement);
   const image = canvas.getByAltText(args.image.alt);
   const title = canvas.getByText(args.heading);
@@ -58,17 +57,20 @@ Standard.play = async ({ args, canvasElement }) => {
   );
   const information = canvas.getByText(args.image.information);
 
-  await expect(image).toBeVisible();
-  await expect(title).toBeVisible();
-  await expect(summary).toBeVisible();
-  await expect(information).not.toBeVisible();
+  await step("Initial load", async () => {
+    await expect(image).toBeVisible();
+    await expect(title).toBeVisible();
+    await expect(summary).toBeVisible();
+    await expect(information).not.toBeVisible();
+  });
 
-  await userEvent.click(summary);
-  await expect(image).toBeVisible();
-  await expect(title).toBeVisible();
-  await expect(summary).toBeVisible();
-  await expect(information).toBeVisible();
+  await step("Open information", async () => {
+    await userEvent.click(summary);
+    await expect(information).toBeVisible();
+  });
 
-  await userEvent.click(summary);
-  await expect(information).not.toBeVisible();
+  await step("Close information", async () => {
+    await userEvent.click(summary);
+    await expect(information).not.toBeVisible();
+  });
 };

package/nationalarchives/components/hero/macro-options.json

@@ -2,7 +2,7 @@
   {
     "name": "heading",
     "type": "string",
-    "required": false,
+    "required": true,
     "description": ""
   },
   {

package/nationalarchives/components/phase-banner/_index.scss

@@ -0,0 +1,43 @@
+@use "../../tools/media";
+@use "../../tools/typography";
+
+.tna-phase-banner {
+  padding-top: 0.375rem;
+  padding-bottom: 0.375rem;
+
+  .tna-container {
+    align-items: center;
+    flex-wrap: nowrap;
+
+    // @include media.on-tiny {
+    //   flex-wrap: wrap;
+    // }
+  }
+
+  &__phase {
+    margin: 0.25rem 0;
+    padding: 0 0.5rem;
+
+    display: block;
+
+    font-weight: 700;
+    text-transform: uppercase;
+    line-height: 1.5;
+
+    background-color: #fff;
+  }
+
+  &__message {
+    margin: 0.25rem 0;
+
+    // @include typography.relative-font-size(14);
+
+    a {
+      color: inherit;
+    }
+  }
+
+  &--beta {
+    background-color: #f9f7e2;
+  }
+}

package/nationalarchives/components/phase-banner/fixtures.json

@@ -0,0 +1,14 @@
+{
+  "component": "phase-banner",
+  "fixtures": [
+    {
+      "name": "beta",
+      "options": {
+        "phase": "Beta",
+        "message": "This is a new service – <a href='#'>give us your feedback</a> to help improve it."
+      },
+      "html": "<div class=\"tna-phase-banner tna-phase-banner--beta\">\n  <div class=\"tna-container\">\n    <div class=\"tna-column\">\n      <span class=\"tna-phase-banner__phase\">\n        Beta\n      </span>\n    </div>\n    <div class=\"tna-column\">\n      <p class=\"tna-phase-banner__message\">\n        This is a new service – <a href='#'>give us your feedback</a> to help improve it.\n      </p>\n    </div>\n  </div>\n</div>",
+      "hidden": false
+    }
+  ]
+}

package/nationalarchives/components/phase-banner/macro-options.json

@@ -0,0 +1,26 @@
+[
+  {
+    "name": "phase",
+    "type": "string",
+    "required": true,
+    "description": ""
+  },
+  {
+    "name": "message",
+    "type": "string",
+    "required": true,
+    "description": ""
+  },
+  {
+    "name": "classes",
+    "type": "string",
+    "required": false,
+    "description": "Classes to add to the phase banner."
+  },
+  {
+    "name": "attributes",
+    "type": "object",
+    "required": false,
+    "description": "HTML attributes (for example data attributes) to add to the phase banner."
+  }
+]

package/nationalarchives/components/phase-banner/macro.njk

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

package/nationalarchives/components/phase-banner/phase-banner.stories.js

@@ -0,0 +1,38 @@
+import PhaseBanner from "./template.njk";
+import macroOptions from "./macro-options.json";
+
+const argTypes = {
+  phase: { control: "text" },
+  message: { control: "text" },
+  classes: { control: "text" },
+  attributes: { control: "object" },
+};
+
+Object.keys(argTypes).forEach((argType) => {
+  argTypes[argType].description = macroOptions.find(
+    (option) => option.name === argType,
+  )?.description;
+});
+
+export default {
+  title: "Components/Phase banner",
+  argTypes,
+};
+
+const Template = ({ phase, message, classes, attributes }) => {
+  return PhaseBanner({
+    params: {
+      phase,
+      message,
+      classes,
+      attributes,
+    },
+  });
+};
+
+export const Standard = Template.bind({});
+Standard.args = {
+  phase: "Beta",
+  message: `This is a new service – <a href="#">give us your feedback</a> to help improve it.`,
+  classes: "tna-phase-banner--demo",
+};

package/nationalarchives/components/phase-banner/template.njk

@@ -0,0 +1,16 @@
+{%- set classes = [params.classes] if params.classes else [] -%}
+{%- set classes = classes.concat('tna-phase-banner--' + params.phase | lower) -%}
+<div class="tna-phase-banner {{ classes | join(' ') }}" {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+  <div class="tna-container">
+    <div class="tna-column">
+      <span class="tna-phase-banner__phase">
+        {{ params.phase }}
+      </span>
+    </div>
+    <div class="tna-column">
+      <p class="tna-phase-banner__message">
+        {{ params.message | safe }}
+      </p>
+    </div>
+  </div>
+</div>

package/nationalarchives/components/sensitive-image/sensitive-image.stories.js

@@ -1,5 +1,4 @@
 import SensitiveImage from "./template.njk";
-import "./_index.scss";
 import macroOptions from "./macro-options.json";
 import { expect } from "@storybook/jest";
 import { within, userEvent } from "@storybook/testing-library";
@@ -20,7 +19,7 @@ Object.keys(argTypes).forEach((argType) => {
 });
 
 export default {
-  title: "Experimental/Sensitive image",
+  title: "Components/Experimental/Sensitive image",
   argTypes,
 };
 

package/nationalarchives/stories/development/contributing.mdx

@@ -0,0 +1,38 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/Contributing" />
+
+# Contributing to the frontend styles
+
+## Adding a new component
+
+1. Create a new directory in `src/nationalarchives/components`
+1. Create an `_index.scss`, `fixtures.json`, `macro-options.json`, `macro.njk`, `template.njk` and a `[myComponent].stories.js` in the directory using other components as a guide
+1. Add the component SCSS to src/nationalarchives/components/_all.scss
+1. Update `tasks/test-package.js` to check for the files as part of the CI (`...componentFiles("myComponent", true)` where `true` ignores the check for any JavaScript files)
+1. Set the macro in `macro.njk` to be `tnaMyComponent` where "MyComponent" is the name of your component
+
+### Files
+
+- `_index.scss` - where you can add your [BEM](https://getbem.com/) SCSS styles for the component
+- `fixtures.json` - these are snapshots of the rendered component's HTML in different scenarios which can be used by other implementations to test against
+- `macro-options.json` - the options for the component which are rendered in the Design System as well as being copied in to the Storybook controls
+- `macro.njk` - the Nunjucks macro easily allows us to include components in the prototype kit and other applications such as the Design System
+- `template.njk` - this is the HTML for the component, written in [Nunjucks](https://mozilla.github.io/nunjucks/)
+- `[myComponent].stories.js` - the stories that get rendered to Storybook
+
+### If you need JavaScript
+
+1. Create a `[myComponent].mjs` file in the component directory
+1. Ensure the top level element in your component has the attribute `data-module="tna-my-component"`
+1. Import and initialise your component as part of the `initAll` function in `src/nationalarchives/all.mjs`
+1. Update the check in `tasks/test-package.js` to remove the `true` and enable checking of the JavaScript file (`...componentFiles("myComponent")`)
+1. If your component uses JavaScript, ensure you add interaction tests using `@storybook/testing-library`
+
+### Best practices
+
+[TODO]
+
+## Updating a component
+
+[TODO]

package/nationalarchives/stories/development/dependencies.mdx

@@ -6,4 +6,6 @@ import { Meta } from "@storybook/blocks";
 
 ```sh
 npx sb upgrade
+# or
+npx storybook@latest upgrade
 ```

package/nationalarchives/stories/development/technologies.mdx

@@ -0,0 +1,65 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/Technologies" />
+
+# Technologies
+
+## Storybook
+
+Most widely supported open source frontend workshop for building UI components, constantly updated, also used by TDR
+
+## ESNext JavaScript (not TypeScript)
+
+JavaScript over TypeScript to allow in-project compilation and possible tree-shaking without extra libraries
+
+## Babel
+
+De facto JavaScript compiler and transpiler, allows us to use most up-to-date JavaScript for increased efficiency and cleaner source code
+
+## SCSS
+
+Most mature CSS preprocessor, used in other TNA projects, huge support
+
+## BEM
+
+Agreed CSS methodology within TNA
+
+## Webpack
+
+Already used in many TNA projects, most mature offering although arguably not the fastest - we could consider changing in the future
+
+## Nunjucks
+
+Used by GDS and made by Mozilla, Nunjucks is simple and expandable and allows us to use components in the GOV.UK prototype kit
+
+## npm
+
+Used by many TNA projects and provides highly available package repository, de facto standard for JavaScript packages
+
+## GitHub actions
+
+Free actions not relying on external services, used on some TNA projects but will allow us to have more of a CI/CD methodology
+
+## Prettier
+
+Opinionated code formatter for (S)CSS, JavaScript, JSON and other file types, intended to reduce bikeshedding
+
+## ESLint
+
+De facto linter for JavaScript to catch potential issues
+
+## Stylelint
+
+Most widely supported and mature (S)CSS linter
+
+## Jest
+
+Lightweight and fast testing library, support for Storybook, easy learning curve
+
+## NVM
+
+Ensures all developers can work on the same version of NodeJS, reduces differences between development environments
+
+## Chromatic.com
+
+Suggested by Storybook for visual regression testing

package/nationalarchives/templates/layouts/_generic.njk

@@ -1,7 +1,7 @@
 {# Based on https://github.com/alphagov/govuk-frontend/blob/8b6bf304b9fc891f64459c25a08f3d623f3fea72/packages/govuk-frontend/src/govuk/template.njk #}
 {#% from "./components/skip-link/macro.njk" import tnaSkipLink -%#}
 <!DOCTYPE html>
-<html lang="{{ htmlLang | default('en') }}" class="tna-template js-disabled {{ htmlClasses }}">
+<html lang="{{ htmlLang | default('en') }}" class="tna-template tna-template--js-disabled {{ htmlClasses }}">
   <head>
   <meta charset="utf-8">
   <title{% if pageTitleLang %} lang="{{ pageTitleLang }}"{% endif %}>{% block pageTitle %}The National Archives{% endblock %}</title>

package/nationalarchives/tools/_all.scss

@@ -1,3 +1,4 @@
+@use "assets";
 @use "grid";
 @use "media";
 @use "typography";

package/nationalarchives/tools/_assets.scss

@@ -0,0 +1,5 @@
+@use "../variables/assets";
+
+@function tna-asset-url($asset) {
+  @return #{assets.$tna-assets-path}/#{$asset};
+}

package/nationalarchives/tools/_media.scss

@@ -1,17 +1,18 @@
 @use "../variables/media";
 
-//   0 ============= 480 ===== 768 == 1024 ==========================
-//   |               |         |      |
-//   | TINY          | SMALL   | MED  | LARGE
-//   |               |         |      |
-//   |<------------->|         .      .            on-tiny
-//   |<----------------------->|      .            on-mobile
+//   0 ======= 320 = 480 ===== 768 == 1024 ========================== min-width/max-width (px)
+//   |         .     |         |      |
+//   |-TINY----------|-SMALL---|-MED--|-LARGE------------------------
+//   |         .     |         |      |
+//   |<------------->|         |      |            on-tiny
+//   |<----------------------->|      |            on-mobile
 //   |<------------------------------>|            on-smaller-than-large
-//   .               |<------->|      .            on-small
-//   .               |<-------------------------   on-larger-than-tiny
-//   .               .         |<---->|            on-medium
-//   .               .         |<---------------   on-larger-than-mobile
-//   .               .         .      |<--------   on-large
+//   |         .     |<------->|      |            on-small
+//   |         .     |<-------------------------   on-larger-than-tiny
+//   |         .     |         |<---->|            on-medium
+//   |         .     |         |<---------------   on-larger-than-mobile
+//   |         .     |         |      |<--------   on-large
+//   |<------->.     |         |      |            Smallest device
 
 @mixin on-large() {
   @media #{media.$media-large} {