@nationalarchives/frontend 0.1.19-prerelease → 0.1.21-prerelease

package/nationalarchives/stories/development/using/npm.mdx

@@ -0,0 +1,59 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/Using/NPM" />
+
+# Using with npm
+
+Install the frontend package from NPM with:
+
+```sh
+npm install @nationalarchives/frontend
+```
+
+## CSS
+
+From here, you have access to include the SCSS files from the package so you can compile the package yourself:
+
+```css
+// OPTIONAL: Override any variables
+@use "node_modules/@nationalarchives/frontend/nationalarchives/variables/assets" with (
+  $tna-font-path: "/MY_CUSTOM_FONTS_PATH",
+  $fa-font-path: "/MY_CUSTOM_FONT_AWESOME_PATH"
+);
+@use "node_modules/@nationalarchives/frontend/nationalarchives/variables/grid" with (
+  $largest-container-width: 1337px
+);
+@use "node_modules/@nationalarchives/frontend/nationalarchives/variables/typography" with (
+  $body-font-size-px: 17
+);
+
+// Include all the styles
+@use "node_modules/@nationalarchives/frontend/nationalarchives/all";
+
+// ...or just include a single component
+@use "node_modules/@nationalarchives/frontend/nationalarchives/components/tabs";
+```
+
+...or you can copy any of the compiled CSS files into your distribution:
+
+- `node_modules/@nationalarchives/frontend/nationalarchives/all.css`
+- `node_modules/@nationalarchives/frontend/nationalarchives/all.css.map`
+- `node_modules/@nationalarchives/frontend/nationalarchives/components/tabs.css`
+- `node_modules/@nationalarchives/frontend/nationalarchives/components/tabs.css.map`
+
+## JavaScript
+
+```JavaScript
+// Import all the JavaScript
+import "node_modules/@nationalarchives/frontend/nationalarchives/all.mjs";
+
+// ...or import just the JavaScript for a single component
+import "node_modules/@nationalarchives/frontend/nationalarchives/components/tabs/tabs.mjs";
+```
+
+...or you can copy any of the compiled JavaScript files into your distribution:
+
+- `node_modules/@nationalarchives/frontend/nationalarchives/all.js`
+- `node_modules/@nationalarchives/frontend/nationalarchives/all.js.map`
+- `node_modules/@nationalarchives/frontend/nationalarchives/components/tabs.js`
+- `node_modules/@nationalarchives/frontend/nationalarchives/components/tabs.js.map`

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

@@ -9,6 +9,7 @@ import Header from "../../../components/header/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 Pagination from "../../../components/pagination/template.njk";
 import PhaseBanner from "../../../components/phase-banner/template.njk";
 import Picture from "../../../components/picture/template.njk";
 import Tabs from "../../../components/tabs/template.njk";
@@ -40,13 +41,13 @@ const Template = ({ theme, accent }) => {
     supertitle: "Card supertitle",
     title: "Card title",
     headingLevel: 3,
-    headingSize: "m",
+    headingSize: "s",
     href: "#",
     imageSrc:
       "https://www.nationalarchives.gov.uk/wp-content/uploads/sites/24/2023/07/tna-building-compress.jpg",
     imageAlt: "The National Archives office",
-    imageWidth: 1996,
-    imageHeight: 1331,
+    imageWidth: 499,
+    imageHeight: 333,
     label: "New",
     body: "<p>Card body</p>",
     actions: [
@@ -86,11 +87,13 @@ const Template = ({ theme, accent }) => {
       : ""
   }">
   <div class="tna-template__body tna-template__body--padded">
+    <!--
     ${CookieBanner({
       params: {
         cookiesUrl: "#",
       },
     })}
+    -->
     ${SkipLink({
       params: {
         href: "main-content",
@@ -156,18 +159,19 @@ const Template = ({ theme, accent }) => {
       ${Hero({
         params: {
           heading: "Title",
-          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,
-          },
+          body: "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
+          imageSrc:
+            "https://www.nationalarchives.gov.uk/wp-content/uploads/sites/24/2023/07/tna-building-compress.jpg",
+          imageAlt: "The National Archives office",
+          imageWidth: 499,
+          imageHeight: 333,
+          imageCaption: "An interesting photo by a famous photographer ©2023",
           classes: "tna-hero--demo",
         },
       })}
       <div class="tna-container tna-section">
         <div class="tna-column tna-column--width-2-3 tna-column--full-small tna-column--full-tiny">
-          <hgroup class="tna-hgroup tna-hgroup--xl">
+          <hgroup class="tna-hgroup tna-hgroup--l">
             <p class="tna-hgroup__supertitle">TNA colour theme</p>
             <h2 class="tna-hgroup__title">Heading</h2>
           </hgroup>
@@ -224,12 +228,36 @@ const Template = ({ theme, accent }) => {
             })}
           </div>
         </div>
-        <div class="tna-column tna-column--width-1-3 tna-column--full-small tna-column--full-tiny">
-          <div class="tna-aside tna-background--contrast tna-!--margin-top-l-small tna-!--margin-top-xl-tiny">
-            <p>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.</p>
-          </div>
-          <div class="tna-aside tna-background--accent">
-            <p>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.</p>
+        <div class="tna-column tna-column--no-padding tna-column--width-1-3 tna-column--full-medium tna-column--full-small tna-column--full-tiny">
+          <div class="tna-container tna-container--no-padding">
+            <div class="tna-column tna-column--full tna-column--width-1-2-medium tna-column--width-1-2-small tna-!--margin-top-l-medium tna-!--margin-top-l-small tna-!--margin-top-l-tiny">
+              <div class="tna-aside tna-background--contrast">
+                <p>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.</p>
+                <div class="tna-button-group">
+                  ${Button({
+                    params: {
+                      text: "Accent button",
+                      href: "#",
+                      accent: true,
+                    },
+                  })}
+                </div>
+              </div>
+            </div>
+            <div class="tna-column tna-column--full tna-column--width-1-2-medium tna-column--width-1-2-small tna-!--margin-top-m tna-!--margin-top-l-medium tna-!--margin-top-l-small tna-!--margin-top-l-tiny">
+              <div class="tna-aside tna-background--accent">
+                <p>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.</p>
+                <div class="tna-button-group">
+                  ${Button({
+                    params: {
+                      text: "Primary button",
+                      href: "#",
+                      classes: "tna-button--solid-hover",
+                    },
+                  })}
+                </div>
+              </div>
+            </div>
           </div>
         </div>
       </div>
@@ -281,17 +309,65 @@ const Template = ({ theme, accent }) => {
             </div>
             <p class="tna-blockquote__author">Douglas Adams, Mostly Harmless</p>
           </blockquote>
-          <h2 class="tna-heading tna-heading--l">
+          <h2 class="tna-heading tna-heading--m">
             <a href="#">Reaerching with The National Archives</a>
           </h2>
           <p>Lorem ipsum <a href="#">link</a></p>
-          <hgroup class="tna-hgroup tna-hgroup--l">
+          <hgroup class="tna-hgroup tna-hgroup--m">
             <p class="tna-hgroup__supertitle">Supertitle</p>
             <h2 class="tna-hgroup__title">
               <a href="#">Reaerching with The National Archives</a>
             </h2>
           </hgroup>
           <p>Lorem ipsum <a href="#">link</a></p>
+        </div>
+        <div class="tna-column tna-column--width-1-2 tna-column--full-small tna-column--full-tiny tna-!--margin-top-m">
+          <h3 class="tna-heading tna-heading--m">
+            Descriptions
+          </h3>
+          <dl class="tna-dl">
+            <dt>Alpha</dt>
+            <dd>Lorem ipsum</dd>
+            <dt>Beta</dt>
+            <dd>Lorem ipsum</dd>
+            <dt>Gamma</dt>
+            <dd>Lorem ipsum</dd>
+          </dl>
+        </div>
+        <div class="tna-column tna-column--width-1-2 tna-column--full-small tna-column--full-tiny tna-!--margin-top-m">
+          <h3 class="tna-heading tna-heading--m">
+            Descriptions
+          </h3>
+          <dl class="tna-dl tna-dl--plain">
+            <dt>Alpha</dt>
+            <dd>Lorem ipsum</dd>
+            <dt>Beta</dt>
+            <dd>Lorem ipsum</dd>
+            <dt>Gamma</dt>
+            <dd>Lorem ipsum</dd>
+          </dl>
+        </div>
+        <div class="tna-column tna-column--full tna-!--margin-top-m">
+          <h3 class="tna-heading tna-heading--m">
+            Descriptions
+          </h3>
+          <dl class="tna-dl tna-dl--icon-padding ">
+            <dt>
+              <i class="fa-solid fa-landmark"></i>
+              Held by
+            </dt>
+            <dd>The National Archives, Kew</dd>
+            <dt>
+              <i class="fa-solid fa-calendar"></i>
+              Date
+            </dt>
+            <dd>1972–1979</dd>
+            <dt>
+              <i class="fa-solid fa-database"></i>
+              Reference
+            </dt>
+            <dd>LC 4</dd>
+          </dl>
           <h2 class="tna-heading tna-heading--l">
             Categories
           </h2>
@@ -325,7 +401,17 @@ const Template = ({ theme, accent }) => {
           <p class="tna-!--no-margin-bottom tna-!--padding-top-xl">Lorem ipsum</p>
         </div>
       </div>
-      <hr>
+      ${Hero({
+        params: {
+          imageSrc:
+            "https://www.nationalarchives.gov.uk/wp-content/uploads/sites/24/2023/07/tna-building-compress.jpg",
+          imageAlt: "The National Archives office",
+          imageWidth: 499,
+          imageHeight: 333,
+          imageCaption: "An interesting photo by a famous photographer ©2023",
+          classes: "tna-hero--demo",
+        },
+      })}
       <div class="tna-container tna-section tna-!--padding-bottom-s">
         <div class="tna-column tna-column--width-1-3 tna-column--width-1-2-small tna-column--full-tiny">
           ${Card({
@@ -420,8 +506,8 @@ const Template = ({ theme, accent }) => {
             params: {
               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,
+              width: 499,
+              height: 333,
               caption: "<p>This is a pretty image</p>",
               transcript: "<p>Lorem ipsum transcript</p>",
               translation: "<p>Lorem ipsum translation</p>",
@@ -521,9 +607,51 @@ const Template = ({ theme, accent }) => {
         })}
         <div class="tna-container">
           <div class="tna-column tna-column--full">
+            ${Pagination({
+              params: {
+                landmarkLabel: "My dogs 1 results",
+                previous: {
+                  href: "#",
+                },
+                items: [
+                  {
+                    number: 1,
+                    href: "#",
+                  },
+                  {
+                    ellipsis: true,
+                  },
+                  {
+                    number: 6,
+                    href: "#",
+                  },
+                  {
+                    number: 7,
+                    current: true,
+                    href: "#",
+                  },
+                  {
+                    number: 8,
+                    href: "#",
+                  },
+                  {
+                    ellipsis: true,
+                  },
+                  {
+                    number: 42,
+                    href: "#",
+                  },
+                ],
+                next: {
+                  href: "#",
+                },
+                classes: "tna-pagination--demo",
+              },
+            })}
             <div class="tna-button-group">
-              <a href="#" class="tna-button">Primary button</a>
-              <a href="#" class="tna-button tna-button--accent">Accent button</a>
+              <a href="#" class="tna-button" role="button">Primary button</a>
+              <a href="#" class="tna-button tna-button--accent" role="button">Accent button</a>
+              <a href="" class="tna-button tna-button--plain" role="button">Plain button</a>
             </div>
           </div>
         </div>
@@ -561,9 +689,51 @@ const Template = ({ theme, accent }) => {
         })}
         <div class="tna-container">
           <div class="tna-column tna-column--full">
+            ${Pagination({
+              params: {
+                landmarkLabel: "My dogs 2 results",
+                previous: {
+                  href: "#",
+                },
+                items: [
+                  {
+                    number: 1,
+                    href: "#",
+                  },
+                  {
+                    ellipsis: true,
+                  },
+                  {
+                    number: 6,
+                    href: "#",
+                  },
+                  {
+                    number: 7,
+                    current: true,
+                    href: "#",
+                  },
+                  {
+                    number: 8,
+                    href: "#",
+                  },
+                  {
+                    ellipsis: true,
+                  },
+                  {
+                    number: 42,
+                    href: "#",
+                  },
+                ],
+                next: {
+                  href: "#",
+                },
+                classes: "tna-pagination--demo",
+              },
+            })}
             <div class="tna-button-group">
-              <a href="#" class="tna-button">Primary button</a>
-              <a href="#" class="tna-button tna-button--accent">Accent button</a>
+              <a href="#" class="tna-button" role="button">Primary button</a>
+              <a href="#" class="tna-button tna-button--accent" role="button">Accent button</a>
+              <a href="" class="tna-button tna-button--plain" role="button">Plain button</a>
             </div>
           </div>
         </div>
@@ -601,9 +771,51 @@ const Template = ({ theme, accent }) => {
         })}
         <div class="tna-container">
           <div class="tna-column tna-column--full">
+            ${Pagination({
+              params: {
+                landmarkLabel: "My dogs 3 results",
+                previous: {
+                  href: "#",
+                },
+                items: [
+                  {
+                    number: 1,
+                    href: "#",
+                  },
+                  {
+                    ellipsis: true,
+                  },
+                  {
+                    number: 6,
+                    href: "#",
+                  },
+                  {
+                    number: 7,
+                    current: true,
+                    href: "#",
+                  },
+                  {
+                    number: 8,
+                    href: "#",
+                  },
+                  {
+                    ellipsis: true,
+                  },
+                  {
+                    number: 42,
+                    href: "#",
+                  },
+                ],
+                next: {
+                  href: "#",
+                },
+                classes: "tna-pagination--demo",
+              },
+            })}
             <div class="tna-button-group">
-              <a href="#" class="tna-button">Primary button</a>
-              <a href="#" class="tna-button tna-button--accent">Accent button</a>
+              <a href="#" class="tna-button" role="button">Primary button</a>
+              <a href="#" class="tna-button tna-button--accent" role="button">Accent button</a>
+              <a href="" class="tna-button tna-button--plain" role="button">Plain button</a>
             </div>
           </div>
         </div>
@@ -641,8 +853,51 @@ const Template = ({ theme, accent }) => {
         })}
         <div class="tna-container">
           <div class="tna-column tna-column--full">
+            ${Pagination({
+              params: {
+                landmarkLabel: "My dogs 4 results",
+                previous: {
+                  href: "#",
+                },
+                items: [
+                  {
+                    number: 1,
+                    href: "#",
+                  },
+                  {
+                    ellipsis: true,
+                  },
+                  {
+                    number: 6,
+                    href: "#",
+                  },
+                  {
+                    number: 7,
+                    current: true,
+                    href: "#",
+                  },
+                  {
+                    number: 8,
+                    href: "#",
+                  },
+                  {
+                    ellipsis: true,
+                  },
+                  {
+                    number: 42,
+                    href: "#",
+                  },
+                ],
+                next: {
+                  href: "#",
+                },
+                classes: "tna-pagination--demo",
+              },
+            })}
             <div class="tna-button-group">
-              <a href="#" class="tna-button">Primary button</a>
+              <a href="#" class="tna-button" role="button">Primary button</a>
+              <a href="#" class="tna-button tna-button--accent" role="button">Accent button</a>
+              <a href="" class="tna-button tna-button--plain" role="button">Plain button</a>
             </div>
           </div>
         </div>
@@ -730,7 +985,7 @@ const Template = ({ theme, accent }) => {
             ],
           },
           {
-            title: "Our websites help",
+            title: "Our websites",
             items: [
               {
                 text: "UK Government Web Archive",

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

@@ -19,7 +19,10 @@ const HeadingsTemplate = ({ text }) =>
   `${HeadingTemplate({ params: { text, size: "xl" } }, 1)}${HeadingTemplate(
     { params: { text, size: "l" } },
     2,
-  )}${HeadingTemplate({ params: { text, size: "m" } }, 3)}`;
+  )}${HeadingTemplate({ params: { text, size: "m" } }, 3)}${HeadingTemplate(
+    { params: { text, size: "s" } },
+    4,
+  )}`;
 
 export const Headings = HeadingsTemplate.bind({});
 Headings.args = {

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

@@ -1,5 +1,6 @@
 const argTypes = {
   items: { control: "object" },
+  plain: { control: "boolean" },
 };
 
 export default {
@@ -36,3 +37,95 @@ OrderedListPlain.args = {
   items: ["Alpha", "Beta", "Gamma"],
   plain: true,
 };
+
+const DescriptionListTemplate = ({ items, plain }) =>
+  `<dl class="tna-dl${plain ? " tna-dl--plain" : ""}${
+    items.some((item) => item.icon) ? " tna-dl--icon-padding" : ""
+  }">${items.reduce(
+    (list, item) => `${list}
+    <dt>
+      ${item.icon ? `<i class="fa-solid fa-${item.icon}"></i>` : ""}
+      ${item.title}
+    </dt>
+    ${
+      Array.isArray(item.description)
+        ? item.description.reduce(
+            (descriptions, description) =>
+              `${descriptions}<dd>${description}</dd>`,
+            "",
+          )
+        : `<dd>${item.description}</dd>`
+    }`,
+    "",
+  )}
+</dl>`;
+
+export const DescriptionList = DescriptionListTemplate.bind({});
+DescriptionList.args = {
+  items: [
+    { title: "Alpha", description: "Lorem ipsum" },
+    { title: "Beta", description: "Lorem ipsum" },
+    { title: "Gamma", description: "Lorem ipsum" },
+    { title: "Delta", description: "Lorem ipsum" },
+    { title: "Epsilon", description: "Lorem ipsum" },
+    { title: "Zeta", description: "Lorem ipsum" },
+    { title: "Eta", description: "Lorem ipsum" },
+  ],
+};
+
+export const PlainDescriptionList = DescriptionListTemplate.bind({});
+PlainDescriptionList.args = {
+  items: [
+    { title: "Alpha", description: "Lorem ipsum" },
+    { title: "Beta", description: "Lorem ipsum" },
+    { title: "Gamma", description: "Lorem ipsum" },
+    { title: "Delta", description: "Lorem ipsum" },
+  ],
+  plain: true,
+};
+
+export const DescriptionListWithIcons = DescriptionListTemplate.bind({});
+DescriptionListWithIcons.args = {
+  items: [
+    {
+      title: "Held by",
+      description: "The National Archives, Kew",
+      icon: "landmark",
+    },
+    { title: "Date", description: "1972&ndash;1979", icon: "calendar" },
+    { title: "Reference", description: "LC 4", icon: "database" },
+  ],
+};
+
+export const PlainDescriptionListWithIcons = DescriptionListTemplate.bind({});
+PlainDescriptionListWithIcons.args = {
+  items: [
+    {
+      title: "Held by",
+      description: "The National Archives, Kew",
+      icon: "landmark",
+    },
+    { title: "Date", description: "1972&ndash;1979", icon: "calendar" },
+    { title: "Reference", description: "LC 4", icon: "database" },
+  ],
+  plain: true,
+};
+
+export const ComplexDescriptionList = DescriptionListTemplate.bind({});
+ComplexDescriptionList.args = {
+  items: [
+    { title: "Alpha", description: "Lorem ipsum" },
+    { title: "Beta", description: "Lorem ipsum" },
+    {
+      title: "Gamma",
+      description: ["Lorem ipsum 1", "Lorem ipsum 2", "Lorem ipsum 3"],
+    },
+    {
+      title: "Delta",
+      description: ["Lorem ipsum 1", "Lorem ipsum 2", "Lorem ipsum 3"],
+    },
+    { title: "Epsilon", description: ["Lorem ipsum 1", "Lorem ipsum 2"] },
+    { title: "Zeta", description: "Lorem ipsum" },
+    { title: "Eta", description: ["Lorem ipsum 1", "Lorem ipsum 2"] },
+  ],
+};

package/nationalarchives/stories/utilities/typography/typography.mdx

@@ -32,7 +32,17 @@ In the second example, the heading will be read as two separate sentences; `Reco
 <Canvas of={TypographyStories.Paragraph} />
 <Canvas of={TypographyStories.Blockquote} />
 <Canvas of={TypographyStories.SceneSetter} />
+
+## Lists
+
 <Canvas of={ListStories.UnorderedList} />
-<Canvas of={ListStories.UnorderedListPlain} />
 <Canvas of={ListStories.OrderedList} />
+<Canvas of={ListStories.DescriptionList} />
+<Canvas of={ListStories.DescriptionListWithIcons} />
+
+### Plain versions
+
+<Canvas of={ListStories.UnorderedListPlain} />
 <Canvas of={ListStories.OrderedListPlain} />
+<Canvas of={ListStories.PlainDescriptionList} />
+<Canvas of={ListStories.PlainDescriptionListWithIcons} />

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

@@ -19,7 +19,7 @@ Paragraph.args = {
 };
 
 const HeadingLinkTemplate = ({ text, href }) =>
-  `<h2 class="tna-heading">
+  `<h2 class="tna-heading tna-heading--s">
     <a href="${href}">${text}</a>
   </h2>`;
 export const HeadingLink = HeadingLinkTemplate.bind({});