@nationalarchives/frontend 0.1.14-prerelease → 0.1.16-prerelease

package/nationalarchives/components/skip-link/macro-options.json

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

package/nationalarchives/components/skip-link/macro.njk

@@ -0,0 +1,3 @@
+{% macro tnaSkipLink(params) %}
+  {%- include "nationalarchives/components/skip-link/template.njk" -%}
+{% endmacro %}

package/nationalarchives/components/skip-link/skip-link.stories.js

@@ -0,0 +1,31 @@
+import SkipLink from "./template.njk";
+import macroOptions from "./macro-options.json";
+
+const argTypes = {
+  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/Skip link",
+  argTypes,
+};
+
+const Template = ({ classes, attributes }) =>
+  `${SkipLink({
+    params: {
+      classes,
+      attributes,
+    },
+  })}<p>To view the skip link component tab to this example, or click inside this example and press tab.</p>`;
+
+export const Standard = Template.bind({});
+Standard.args = {
+  classes: "tna-skip-link--demo",
+};

package/nationalarchives/components/skip-link/template.njk

@@ -0,0 +1,4 @@
+{%- set containerClasses = [params.classes] if params.classes else [] -%}
+<a href="#{{ params.href if params.href else 'main-content' }}" class="tna-skip-link {{ containerClasses | join(' ') }}" {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+  {{ params.text if params.text else 'Skip to main content' }}
+</a>

package/nationalarchives/components/tabs/_index.scss

@@ -1,7 +1,11 @@
 @use "../../tools/colour";
 
 .tna-tabs {
-  margin-bottom: 1rem;
+  margin-bottom: 2rem;
+
+  &:last-child {
+    margin-bottom: 0;
+  }
 
   &__list {
     margin: 0 0 1rem;
@@ -124,25 +128,14 @@
     }
   }
 
-  @mixin high-contrast {
+  @include colour.on-high-contrast {
     &__list-item-link {
       padding-right: 1rem;
       padding-left: 1rem;
 
       overflow: hidden;
 
-      border: 1px transparent solid;
-      @include colour.colour-border("keyline-dark");
-    }
-  }
-
-  .tna-template--high-contrast-theme & {
-    @include high-contrast;
-  }
-
-  @media (prefers-contrast: more) {
-    .tna-template--system-theme & {
-      @include high-contrast;
+      @include colour.colour-border("keyline-dark", 1px);
     }
   }
 }

package/nationalarchives/components/tabs/tabs.stories.js

@@ -22,8 +22,8 @@ export default {
   argTypes,
 };
 
-const Template = ({ title, items, sticky, classes, attributes }) => {
-  return Tabs({
+const Template = ({ title, items, sticky, classes, attributes }) =>
+  Tabs({
     params: {
       title,
       items,
@@ -32,7 +32,6 @@ const Template = ({ title, items, sticky, classes, attributes }) => {
       attributes,
     },
   });
-};
 
 export const Standard = Template.bind({});
 Standard.args = {

package/nationalarchives/patterns/featured-collection/_index.scss

@@ -1,10 +1,10 @@
-@use "../../variables/colour" as colourVars;
+@use "../../tools/colour";
 
 .tna-featured-collection {
   padding-top: 2rem;
   padding-bottom: 2rem;
 
-  background-color: colourVars.$tna-cream;
+  background-color: colour.brand-colour("cream");
 
   .tna-card {
     margin-top: 1rem;

package/nationalarchives/patterns/featured-collection/featured-collection.stories.js

@@ -14,19 +14,18 @@ Object.keys(argTypes).forEach((argType) => {
 });
 
 export default {
-  title: "Experimental/Patterns/Featured collection",
+  title: "Patterns/Experimental/Featured collection",
   argTypes,
 };
 
-const Template = ({ heading, classes, attributes }) => {
-  return FeaturedCollection({
+const Template = ({ heading, classes, attributes }) =>
+  FeaturedCollection({
     params: {
       heading,
       classes,
       attributes,
     },
   });
-};
 
 export const Standard = Template.bind({});
 Standard.args = {

package/nationalarchives/patterns/featured-collection/template.njk

@@ -43,9 +43,9 @@
         href: "#",
         image: {
           src: "https://picsum.photos/id/29/640/360",
-          alt: "A placeholder image",
-          label: "Feature"
+          alt: "A placeholder image"
         },
+        label: "Feature",
         body: "<p>Card body</p>"
       })
     },

package/nationalarchives/stories/utilities/colour-schemes/colour-schemes.mdx

@@ -0,0 +1,85 @@
+import { Meta, Canvas } from "@storybook/blocks";
+import * as ColourStories from './colour-schemes.stories';
+
+<Meta of={ColourStories} />
+
+# Colour schemes
+
+## System theme
+
+The system theme follows the operating system preference for `prefers-color-scheme` which can either be `light` or `dark`.
+
+The system theme also follows the preference for `prefers-contrast` which can be `no-preference`, `more`, `less` or `custom`.
+
+At this time, only `prefers-contrast: no-preference` and `prefers-contrast: more` are supported.
+
+- [MDN Web Docs - prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
+- [MDN Web Docs - prefers-contrast](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast)
+
+```html
+<html class="tna-template tna-template--system-theme">
+  <head>
+    <title>System theme</title>
+  </head>
+  <body class="tna-template__body">
+  </body>
+</html>
+```
+
+## Light theme
+
+```html
+<html class="tna-template tna-template--light-theme">
+  <head>
+    <title>Light theme</title>
+  </head>
+  <body class="tna-template__body">
+  </body>
+</html>
+```
+
+## Dark theme
+
+```html
+<html class="tna-template tna-template--dark-theme">
+  <head>
+    <title>Dark theme</title>
+  </head>
+  <body class="tna-template__body">
+  </body>
+</html>
+```
+
+## High contrast themes
+
+The high contrast themes are applied on top of the existing light and dark themes with an extra `tna-template--high-contrast-theme` class on the `tna-template` element.
+
+### Light, high contrast theme
+
+```html
+<html class="tna-template tna-template--light-theme tna-template--high-contrast-theme">
+  <head>
+    <title>Light, high contrast theme</title>
+  </head>
+  <body class="tna-template__body">
+  </body>
+</html>
+```
+
+### Dark, high contrast theme
+
+```html
+<html class="tna-template tna-template--dark-theme tna-template--high-contrast-theme">
+  <head>
+    <title>Dark, high contrast theme</title>
+  </head>
+  <body class="tna-template__body">
+  </body>
+</html>
+```
+
+## Colour definitions
+
+The colours are defined in `src/nationalarchives/variables/_colour.scss` as a separate map for each theme.
+
+This allows you to reference a colour, such as `font-base` without having to worry about which theme is currently in use.

package/nationalarchives/stories/utilities/{colour.stories.js → colour-schemes/colour-schemes.stories.js}

@@ -1,13 +1,13 @@
-import Header from "../../components/header/template.njk";
-import Breadcrumbs from "../../components/breadcrumbs/template.njk";
-import Card from "../../components/card/template.njk";
-import Hero from "../../components/hero/template.njk";
-import IndexGrid from "../../components/index-grid/template.njk";
-import Message from "../../components/message/template.njk";
-import Picture from "../../components/picture/template.njk";
-import Tabs from "../../components/tabs/template.njk";
-import Footer from "../../components/footer/template.njk";
-import { supportDynamicColourSchemes } from "../../../../.storybook/preview";
+import SkipLink from "../../../components/skip-link/template.njk";
+import Header from "../../../components/header/template.njk";
+import Breadcrumbs from "../../../components/breadcrumbs/template.njk";
+import Card from "../../../components/card/template.njk";
+import Hero from "../../../components/hero/template.njk";
+import IndexGrid from "../../../components/index-grid/template.njk";
+import Message from "../../../components/message/template.njk";
+import Picture from "../../../components/picture/template.njk";
+import Tabs from "../../../components/tabs/template.njk";
+import Footer from "../../../components/footer/template.njk";
 
 const argTypes = {
   theme: {
@@ -23,15 +23,11 @@ const argTypes = {
 };
 
 export default {
-  title: "Experimental/Utilities/Colour themes",
+  title: "Utilities/Colour schemes",
   argTypes,
 };
 
 const Template = ({ theme }) => {
-  if (supportDynamicColourSchemes) {
-    // document.documentElement.classList.remove("tna-template--light-theme");
-    // document.documentElement.classList.add("tna-template--system-theme");
-  }
   return `<div class="tna-template ${
     theme === "system"
       ? "tna-template--system-theme"
@@ -46,8 +42,17 @@ const Template = ({ theme }) => {
       : ""
   }">
   <div class="tna-template__body tna-template__body--padded">
+    ${SkipLink({
+      params: {
+        href: "main-content",
+      },
+    })}
     ${Header({
       params: {
+        logo: {
+          strapline: "Colours",
+          href: "#/",
+        },
         navigation: [
           {
             text: "Alpha",
@@ -92,7 +97,7 @@ const Template = ({ theme }) => {
         ],
       },
     })}
-    <article>
+    <main id="main-content" role="main">
       ${Hero({
         params: {
           heading: "Title",
@@ -111,7 +116,6 @@ const Template = ({ theme }) => {
             <p class="tna-hgroup__supertitle">TNA colour theme</p>
             <h2 class="tna-hgroup__title">Heading</h2>
           </hgroup>
-          <hr>
           <p class="tna-p">Lorem ipsum <a href="#">link</a></p>
           <ul class="tna-ul">
             <li>Alpha</li>
@@ -120,13 +124,33 @@ const Template = ({ theme }) => {
           </ul>
           <a href="#" class="tna-button">Primary button</a>
           <a href="#" class="tna-button tna-button--secondary">Secondary button</a>
-          <hr>
+        </div>
+      </div>
+      <hr>
+      <div class="tna-container">
+        <div class="tna-column tna-column--full">
+          <p class="tna-!--no-margin-bottom">Lorem ipsum</p>
+          <p class="tna-!--no-margin-bottom tna-!__padding-top--xs">Lorem ipsum</p>
+          <p class="tna-!--no-margin-bottom tna-!__padding-top--s">Lorem ipsum</p>
+          <p class="tna-!--no-margin-bottom tna-!__padding-top--m">Lorem ipsum</p>
+          <p class="tna-!--no-margin-bottom tna-!__padding-top--l">Lorem ipsum</p>
+          <p class="tna-!--no-margin-bottom tna-!__padding-top--xl">Lorem ipsum</p>
+        </div>
+      </div>
+      <hr>
+      <div class="tna-container">
+        <div class="tna-column tna-column--full">
           ${Message({
             params: {
               message:
                 "Please note this page references hunger strikes and force feeding, which some people may find upsetting.",
             },
           })}
+        </div>
+      </div>
+      <hr>
+      <div class="tna-container">
+        <div class="tna-column tna-column--full">
           ${Card({
             params: {
               heading: {
@@ -143,10 +167,50 @@ const Template = ({ theme }) => {
                 width: 1996,
                 height: 1331,
               },
+              label: "New",
               body: "<p>Card body</p>",
               classes: "tna-card--demo",
             },
           })}
+        </div>
+      </div>
+      <hr>
+      <div class="tna-container">
+        <div class="tna-column tna-column--full">
+          ${Card({
+            params: {
+              heading: {
+                supertitle: "Card supertitle",
+                title: "Card title",
+                level: 3,
+                size: "l",
+                singleSentence: false,
+              },
+              href: "#",
+              image: {
+                src: "https://www.nationalarchives.gov.uk/wp-content/uploads/sites/24/2023/07/tna-building-compress.jpg",
+                alt: "The National Archives office",
+                width: 1996,
+                height: 1331,
+              },
+              label: "New",
+              body: "<p>Card body</p>",
+              actions: [
+                {
+                  text: "Card action",
+                  href: "#",
+                  title: "Go and do the action",
+                },
+              ],
+              featured: true,
+              classes: "tna-card--demo",
+            },
+          })}
+        </div>
+      </div>
+      <hr>
+      <div class="tna-container">
+        <div class="tna-column tna-column--full">
           ${Tabs({
             params: {
               title: "Example tabs",
@@ -170,6 +234,11 @@ const Template = ({ theme }) => {
               classes: "tna-tabs--demo",
             },
           })}
+        </div>
+      </div>
+      <hr>
+      <div class="tna-container">
+        <div class="tna-column tna-column--full">
           ${Picture({
             params: {
               src: "https://www.nationalarchives.gov.uk/wp-content/uploads/sites/24/2023/07/tna-building-compress.jpg",
@@ -182,46 +251,67 @@ const Template = ({ theme }) => {
               classes: "tna-picture--demo",
             },
           })}
-          ${IndexGrid({
-            params: {
-              heading: "My dogs",
-              items: Array(12)
-                .fill({
-                  ...{
-                    href: "#",
-                    src: "https://picsum.photos/id/237/800/600",
-                    alt: "Photo of a puppy",
-                    width: "800",
-                    height: "600",
-                    title: "Cat",
-                    subtitle: "4 photos",
-                  },
-                })
-                .map((item, index) => {
-                  const pseudoRandom = ((index * 29) % 8) + 1;
-                  return {
-                    ...item,
-                    href: `#/category-${index}`,
-                    title: `Category #${index + 101}`,
-                    subtitle: `${pseudoRandom} photos`,
-                  };
-                }),
-              columns: 4,
-              columnsMedium: 3,
-              columnsSmall: 2,
-              columnsTiny: 1,
-            },
-          })}
         </div>
       </div>
-    <article>
+      <hr>
+      ${IndexGrid({
+        params: {
+          heading: "My dogs",
+          items: Array(12)
+            .fill({
+              ...{
+                href: "#",
+                src: "https://picsum.photos/id/237/800/600",
+                alt: "Photo of a puppy",
+                width: "800",
+                height: "600",
+                title: "Cat",
+                subtitle: "4 photos",
+              },
+            })
+            .map((item, index) => {
+              const pseudoRandom = ((index * 29) % 8) + 1;
+              return {
+                ...item,
+                href: `#/category-${index}`,
+                title: `Category #${index + 101}`,
+                subtitle: `${pseudoRandom} photos`,
+              };
+            }),
+          columns: 4,
+          columnsMedium: 3,
+          columnsSmall: 2,
+          columnsTiny: 1,
+        },
+      })}
+    </main>
     ${Footer({})}
   </div>
 </div>`;
 };
 
-export const Examples = Template.bind({});
-// Examples.parameters = { options: { showPanel: false } };
-Examples.args = {
+export const System = Template.bind({});
+// System.parameters = { options: { showPanel: false } };
+System.args = {
+  theme: "system",
+};
+
+export const Light = Template.bind({});
+Light.args = {
   theme: "light",
 };
+
+export const Dark = Template.bind({});
+Dark.args = {
+  theme: "dark",
+};
+
+export const LightHighContrast = Template.bind({});
+LightHighContrast.args = {
+  theme: "light high-contrast",
+};
+
+export const DarkHighContrast = Template.bind({});
+DarkHighContrast.args = {
+  theme: "dark high-contrast",
+};

package/nationalarchives/stories/utilities/overrides/overrides.mdx

@@ -0,0 +1,66 @@
+import { Meta, Canvas } from "@storybook/blocks";
+import * as OverrideStories from './overrides.stories';
+
+<Meta of={OverrideStories} />
+
+# Overrides
+
+## Margin
+
+### Top
+
+- `tna-!--no-margin-top`
+- `tna-!--margin-top-xs`
+- `tna-!--margin-top-s`
+- `tna-!--margin-top-m`
+- `tna-!--margin-top-l`
+- `tna-!--margin-top-xl`
+
+### Bottom
+
+- `tna-!--no-margin-bottom`
+- `tna-!--margin-bottom-xs`
+- `tna-!--margin-bottom-s`
+- `tna-!--margin-bottom-m`
+- `tna-!--margin-bottom-l`
+- `tna-!--margin-bottom-xl`
+
+### Vertical (top and bottom)
+
+- `tna-!--no-margin-vertical`
+- `tna-!--margin-vertical-xs`
+- `tna-!--margin-vertical-s`
+- `tna-!--margin-vertical-m`
+- `tna-!--margin-vertical-l`
+- `tna-!--margin-vertical-xl`
+
+## Padding
+
+### Top
+
+- `tna-!--no-padding-top`
+- `tna-!--padding-top-xs`
+- `tna-!--padding-top-s`
+- `tna-!--padding-top-m`
+- `tna-!--padding-top-l`
+- `tna-!--padding-top-xl`
+
+### Bottom
+
+- `tna-!--no-padding-bottom`
+- `tna-!--padding-bottom-xs`
+- `tna-!--padding-bottom-s`
+- `tna-!--padding-bottom-m`
+- `tna-!--padding-bottom-l`
+- `tna-!--padding-bottom-xl`
+
+### Vertical (top and bottom)
+
+- `tna-!--no-padding-vertical`
+- `tna-!--padding-vertical-xs`
+- `tna-!--padding-vertical-s`
+- `tna-!--padding-vertical-m`
+- `tna-!--padding-vertical-l`
+- `tna-!--padding-vertical-xl`
+
+

package/nationalarchives/stories/utilities/overrides/overrides.stories.js

@@ -0,0 +1,30 @@
+const argTypes = {
+  marginTop: {
+    control: "radio",
+    options: ["none", "xs", "s", "m", "l", "xl"],
+  },
+};
+
+export default {
+  title: "Utilities/Overrides",
+  argTypes,
+};
+
+const Template = ({ marginTop }) => {
+  const marginClass =
+    marginTop === "none"
+      ? `tna-!--no-margin-top`
+      : `tna-!--margin-top-${marginTop}`;
+  return `<p class="tna-!--margin-bottom-xl">Lorem ipsum (tna-!--margin-bottom-xl)</p>
+    <p class="tna-!--margin-bottom-l">Lorem ipsum (tna-!--margin-bottom-l)</p>
+    <p class="tna-!--margin-bottom-m">Lorem ipsum (tna-!--margin-bottom-m)</p>
+    <p class="tna-!--margin-bottom-s">Lorem ipsum (tna-!--margin-bottom-s)</p>
+    <p class="tna-!--margin-bottom-xs">Lorem ipsum (tna-!--margin-bottom-xs)</p>
+    <p class="tna-!--no-margin-bottom">Lorem ipsum (tna-!--no-margin-bottom)</p>
+    <p class="${marginClass}">Lorem ipsum (${marginClass})</p>`;
+};
+
+export const Margin = Template.bind({});
+Margin.args = {
+  marginTop: "none",
+};

package/nationalarchives/stories/utilities/{headings.stories.js → typography/headings.stories.js}

@@ -12,7 +12,8 @@ const HeadingTemplate = ({ params }, level) => `<h${level} class="tna-heading${
   params.size ? ` tna-heading--${params.size}` : ""
 }">
   ${params.text} (${params.size.toUpperCase()})
-</h${level}>`;
+</h${level}>
+`;
 
 const HeadingsTemplate = ({ text }) =>
   `${HeadingTemplate({ params: { text, size: "xl" } }, 1)}${HeadingTemplate(

package/nationalarchives/stories/utilities/typography/typography.stories.js

@@ -0,0 +1,34 @@
+const argTypes = {
+  text: { control: "text" },
+};
+
+export default {
+  title: "Utilities/Typography",
+  argTypes,
+};
+
+const ParagraphTemplate = ({ paragraphs }) =>
+  paragraphs.map((paragraph) => `<p class="tna-p">${paragraph}</p>`).join("");
+export const Paragraph = ParagraphTemplate.bind({});
+Paragraph.args = {
+  paragraphs: [
+    "This is some body text.",
+    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam vel tincidunt velit, a molestie turpis. Sed odio libero, sodales eleifend lorem sit amet, feugiat consequat nibh. Donec ac tellus in dui rutrum maximus. Aliquam vel euismod eros. Integer ut magna velit. Fusce sed dui sit amet metus eleifend dictum quis vitae mi. Aenean sagittis euismod purus, in accumsan metus venenatis nec. Nullam nec velit felis. Sed nec felis eu nisl varius dictum eu quis nisl. Donec dapibus est arcu, vel pellentesque risus pellentesque eget.",
+    "Nam a posuere lectus. Vivamus facilisis est pretium augue aliquet iaculis. Phasellus ligula orci, commodo eget lectus et, tincidunt scelerisque erat. Aliquam in est vel purus ultricies vulputate non sed ligula. Pellentesque ut felis ullamcorper, eleifend erat dapibus, feugiat metus. Phasellus vitae dolor commodo, posuere nisl sed, luctus mauris. Etiam malesuada tincidunt enim, ac fermentum est pulvinar id. Maecenas id accumsan libero. Curabitur at velit nisi. Nullam gravida mauris quam, tempor pharetra risus venenatis vel. Proin quis malesuada lacus. Nulla condimentum facilisis turpis, et elementum leo. Nulla gravida quam mauris, id scelerisque est rhoncus ac.",
+  ],
+};
+
+const BlockquoteTemplate = ({
+  html,
+  author,
+}) => `<blockquote class="tna-blockquote">
+  <div class="tna-blockquote__quote">
+    ${html}
+  </div>
+  <p class="tna-blockquote__author">${author}</p>
+</p>`;
+export const Blockquote = BlockquoteTemplate.bind({});
+Blockquote.args = {
+  html: "<p>A common mistake that people make when trying to design something completely foolproof is to underestimate the ingenuity of complete fools.</p>",
+  author: "Douglas Adams, Mostly Harmless",
+};