@nationalarchives/frontend 0.1.3-prerelease → 0.1.6-prerelease

package/nationalarchives/components/grid/_index.scss

@@ -1,84 +1,159 @@
 @use "sass:math";
+@use "../../variables/grid";
+@use "../../variables/media";
+@use "../../tools/grid" as tools;
+
+.tna-container {
+  max-width: grid.$largest-container-width;
+  width: 100%;
+  margin-right: auto;
+  margin-left: auto;
+  padding-right: math.div(grid.$gutter-width, 2);
+  padding-left: math.div(grid.$gutter-width, 2);
+
+  box-sizing: border-box;
+
+  display: -ms-flexbox;
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: stretch;
+  align-items: stretch;
+
+  &.tna-container--max {
+    max-width: none;
+  }
 
-@import "../../variables/all";
-@import "../../utilities/grid";
+  &.tna-container--no-padding {
+    max-width: grid.$largest-container-width - (grid.$gutter-width * 2);
+    padding-right: 0;
+    padding-left: 0;
 
-@include nationalarchives-exports("nationalarchives/utilities/grid") {
-  .tna-container {
-    max-width: $largest-container-width;
-    width: 100%;
-    margin-right: auto;
-    margin-left: auto;
-    padding-right: math.div($gutter-width, 2);
-    padding-left: math.div($gutter-width, 2);
+    .tna-column {
+      padding-right: 0;
+      padding-left: 0;
+    }
+  }
+}
 
-    box-sizing: border-box;
+.tna-column {
+  padding-right: math.div(grid.$gutter-width, 2);
+  padding-left: math.div(grid.$gutter-width, 2);
 
-    display: -ms-flexbox;
-    display: flex;
-    flex-wrap: wrap;
-    justify-content: stretch;
-    align-items: stretch;
+  box-sizing: border-box;
 
-    &.tna-container--max {
-      max-width: none;
-    }
+  &.tna-column--full {
+    width: 100%;
+  }
 
-    &.tna-container--no-padding {
-      max-width: $largest-container-width - ($gutter-width * 2);
-      padding-right: 0;
-      padding-left: 0;
+  // &.column--no-padding {
+  //   padding-right: 0;
+  //   padding-left: 0;
+  // }
+}
 
-      .tna-column {
-        padding-right: 0;
-        padding-left: 0;
-      }
-    }
+@for $i from 1 through 3 {
+  .tna-column--flex-#{$i} {
+    flex: $i 0;
   }
+}
 
-  .tna-column {
-    padding-right: math.div($gutter-width, 2);
-    padding-left: math.div($gutter-width, 2);
-
-    box-sizing: border-box;
+//   @for $i from 1 through 3 {
+//     .column--order-#{$i} {
+//       order: $i;
+//     }
+//   }
 
-    &.tna-column--full {
-      width: 100%;
-    }
+@include tools.columns-generator(grid.$column-count);
 
-    // &.column--no-padding {
-    //   padding-right: 0;
-    //   padding-left: 0;
-    // }
+@media #{media.$media-medium} {
+  .tna-column--full-medium {
+    width: 100%;
+    flex: none;
   }
 
   @for $i from 1 through 3 {
-    .tna-column--flex-#{$i} {
+    .tna-column--flex-#{$i}-medium {
       flex: $i 0;
     }
   }
 
+  // @for $i from 1 through 3 {
+  //   .column--order-#{$i}-medium {
+  //     order: $i;
+  //   }
+  // }
+
+  @include tools.columns-generator(grid.$column-count-medium, "-medium");
+}
+
+@media #{media.$media-mobile} {
+  .tna-container {
+    padding-right: math.div(grid.$gutter-width-mobile, 2) + 0.75rem;
+    padding-left: math.div(grid.$gutter-width-mobile, 2) + 0.75rem;
+  }
+
+  .tna-column {
+    padding-right: math.div(grid.$gutter-width-mobile, 2);
+    padding-left: math.div(grid.$gutter-width-mobile, 2);
+  }
+
+  // .column--width-full-mobile {
+  //   width: 100%;
+  // }
+
+  // @for $i from 1 through 3 {
+  //   .column--flex-#{$i}-mobile {
+  //     flex: $i 0;
+  //   }
+  // }
+
   //   @for $i from 1 through 3 {
-  //     .column--order-#{$i} {
+  //     .column--order-#{$i}-mobile {
   //       order: $i;
   //     }
   //   }
+}
 
-  @include columns-generator($column-count);
-
-  @media #{$media-medium} {
-    @include grid-medium;
+@media #{media.$media-small} {
+  .tna-column--full-small {
+    width: 100%;
+    flex: none;
   }
 
-  @media #{$media-mobile} {
-    @include grid-mobile;
+  @for $i from 1 through 3 {
+    .tna-column--flex-#{$i}-small {
+      flex: $i 0;
+    }
   }
 
-  @media #{$media-small} {
-    @include grid-small;
+  // @for $i from 1 through 3 {
+  //   .column--order-#{$i}-small {
+  //     order: $i;
+  //   }
+  // }
+
+  @include tools.columns-generator(grid.$column-count-small, "-small");
+}
+
+@media #{media.$media-tiny} {
+  .tna-column--full-tiny {
+    width: 100%;
+    flex: none;
   }
 
-  @media #{$media-tiny} {
-    @include grid-tiny;
+  @for $i from 1 through 3 {
+    .tna-column--flex-#{$i}-tiny {
+      width: auto;
+
+      flex: $i 0;
+    }
   }
+
+  // @for $i from 1 through 3 {
+  //   .column--order-#{$i}-tiny {
+  //     order: $i;
+  //   }
+  // }
+
+  @include tools.columns-generator(grid.$column-count-tiny, "-tiny");
 }

package/nationalarchives/components/grid/grid.stories.js

@@ -1,6 +1,5 @@
 import Header from "./template.njk";
-import "../../all.scss";
-import "./_grid.scss";
+import "./_index.scss";
 import macroOptions from "./macro-options.json";
 
 const argTypes = {
@@ -19,7 +18,7 @@ Object.keys(argTypes).forEach((argType) => {
 });
 
 export default {
-  title: "Utilities/Grid",
+  title: "Components/Grid",
   argTypes,
 };
 

package/nationalarchives/components/sensitive-image/_index.scss

@@ -1,84 +1,81 @@
-@include nationalarchives-exports(
-  "nationalarchives/components/sensitive-image"
-) {
-  .tna-sensitive-image {
-  }
+@use "../../tools/typography" as typographyTools;
 
-  .tna-sensitive-image__warning {
-  }
+.tna-sensitive-image {
+}
 
-  .tna-sensitive-image__details {
-    position: relative;
+.tna-sensitive-image__warning {
+}
 
-    // overflow: hidden;
+.tna-sensitive-image__details {
+  position: relative;
 
-    &::after {
-      width: 100%;
-      padding-bottom: calc(
-        100% * var(--sensitive-image-height) / var(--sensitive-image-width)
-      );
+  // overflow: hidden;
 
-      display: block;
+  &::after {
+    width: 100%;
+    padding-bottom: calc(
+      100% * var(--sensitive-image-height) / var(--sensitive-image-width)
+    );
 
-      position: relative;
-      z-index: -1;
+    display: block;
 
-      background-image: var(--sensitive-image);
-      background-clip: padding-box;
-      background-size: contain;
+    position: relative;
+    z-index: -1;
 
-      filter: blur(15px) saturate(0);
+    background-image: var(--sensitive-image);
+    background-clip: padding-box;
+    background-size: contain;
 
-      content: "";
-    }
+    filter: blur(20px) saturate(0);
+
+    content: "";
   }
+}
 
-  .tna-sensitive-image__show {
-    display: flex;
-    align-items: center;
-    justify-content: center;
+.tna-sensitive-image__show {
+  display: flex;
+  align-items: center;
+  justify-content: center;
 
-    position: absolute;
-    top: 0;
-    right: 0;
-    bottom: 0;
-    left: 0;
-    z-index: 1;
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 1;
 
-    font-size: 0;
+  font-size: 0;
 
-    cursor: pointer;
+  cursor: pointer;
 
-    &::after {
-      padding: 0.5rem 2rem;
+  &::after {
+    padding: 0.5rem 2rem;
 
-      font-size: 1rem;
+    @include typographyTools.relativeFontSize(16);
+    background-color: #ff0;
 
-      background-color: #ff0;
-
-      content: attr(data-action);
-    }
+    content: attr(data-action);
+  }
 
-    &:hover {
-      &::after {
-        color: #fff;
+  &:hover {
+    &::after {
+      color: #fff;
 
-        background-color: #000;
-      }
+      background-color: #000;
     }
   }
+}
 
-  .tna-sensitive-image__container {
-  }
+.tna-sensitive-image__container {
+}
 
-  .tna-sensitive-image__image {
-    width: 100%;
-  }
+.tna-sensitive-image__image {
+  width: 100%;
+}
 
-  .tna-sensitive-image__details[open] {
-    &::after,
-    .tna-sensitive-image__show {
-      display: none;
-    }
+.tna-sensitive-image__details[open] {
+  &::after,
+  .tna-sensitive-image__show {
+    display: none;
   }
 }

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

@@ -1,6 +1,5 @@
 import SensitiveImage from "./template.njk";
-import "../../all.scss";
-import "./_sensitive-image.scss";
+import "./_index.scss";
 import macroOptions from "./macro-options.json";
 
 const argTypes = {

package/nationalarchives/stories/design/about.mdx

@@ -0,0 +1,25 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Design/Prototyping" />
+
+# Prototyping with the styles
+
+The National Archives frontend styles include support for the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk/).
+
+You can use the components and styles within the prototype kit to make rich HTML prototypes.
+
+## Create a new prototype
+
+1. Create an empty directory `mkdir my-new-prototype`
+1. Use `npx govuk-prototype-kit create` to create a new prototype project
+1. Install the frontend styles with `npm install @nationalarchives/frontend`
+1. Run `npm run dev` to start up the prototype kit
+1. Use the National Archives components!
+
+```Nunjucks
+{% from "nationalarchives/components/button/macro.njk" import tnaButton %}
+{{ tnaButton({
+  text: "I am a button",
+  url: "#"
+}) }}
+```

package/nationalarchives/stories/development/about.mdx

@@ -0,0 +1,62 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/About" />
+
+# Project history
+
+## Needs
+
+TNA needed a frontend toolkit that was:
+
+- standardised - a single source of truth for all TNA that follows all our coding standards (currently non-existent)
+- version controlled - as well as [semantically versioned](https://semver.org/) with a [changelog](https://keepachangelog.com/en/1.0.0/)
+- open - all source code should be [open and available to anyone](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open)
+- accessible - all components meet WCAG 2.1 AA standards
+- progressively enhanced - all components should still be operable without JavaScript, CSS or both
+- importable into projects (via a service such as [NPM](https://www.npmjs.com/search?q=nationalarchives)) - to make dependency management as simple as possible
+- agnostic - the implementation for the markup of the components can be replicated in any required technology (because we have Python, PHP and Java applications throughout the organisation)
+- testable - both from an internal perspective as well as providing scenarios and expected results for language implimentations to be able to validate against
+- lean - minimal reliance on other languages and dependencies to ensure good extendability and speed of development and deployment
+- automatically published - leveraging CI/CD, creating a new release version should be as simple as possible
+
+It would have also been nice to have a toolkit that was:
+
+- extendable - rather than providing a static snapshot of the toolkit, we should always be able to extend it for any given application
+- documentable - not just from a technical perspective but also from a user-centred design perspective with best practices of when and how to use each component (this might be a separate project where we can [share information such as user research](https://www.gov.uk/service-manual/service-standard/point-13-use-common-standards-components-patterns))
+- prototype-able - by using Nunjucks, we could easily create a toolkit that integrated with the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk/docs/) which means we could very easily create high fidelity prototypes to test with, ultimately helping with user research
+
+## Current solutions
+
+There was already a solution in [nationalarchives/tdr-components](https://github.com/nationalarchives/tdr-components) which is specific to TDR and extends the GOV.UK components and styles. We needed to create a more generic set of components that were suitable for every TNA service, ~~while still extending the GOV.UK components and styles~~ *[Edit: this was not implemented]* but with a more TNA-branded look and feel.
+
+We also had [nationalarchives/tna-frontend-design-toolkit](https://github.com/nationalarchives/tna-frontend-design-toolkit) which aimed to provide similar functionality but wasn't as featureful as we needed and wasn't published to NPM which means it has to be [copied into the projects that require it](https://github.com/nationalarchives/ds-wagtail/tree/develop/sass/tna-toolkit).
+
+## Proposed solution
+
+This repository should hold all the JavaScript and SCSS source files required for all the frontend styles along with tests and expected markup.
+
+### Output
+
+The source files will be compiled down to a NodeJS package and deployed to [NPM](https://www.npmjs.com/). The package will contain:
+
+- All the JavaScript and SCSS source files which can be imported into a projects source code and compiled by the project (which will allow for tree shaking and application-specific modifications)
+- An AMD/UMD/IIFE (TBD) ES5 JavaScript file which can be included with a normal `<script>` element
+- A single CSS file containing all the styles which can be included with a normal `<style>` element
+- The Nunjucks templates for each component that might be required in other projects such as prototyping tools (other implementations can be made such as [Jinja templates](https://github.com/nationalarchives/tna-frontend-jinja))
+
+### Component resources
+
+Each component in this repository should contain:
+
+- Nunjucks template - only used to display the component within the examples page and aid development
+- SCSS - which could either be imported as a standalone styles declaration or as part of the compiled output
+- JavaScript (ESNext) - if there is any progressive enhancement required on the component
+- Options/properties - a list of the configurable properties of the component and their types
+- Test scenarios - a variety of configurations and their expected outputs that can be used by either this repository or other implementations of the components (e.g. Jinja)
+
+### Technologies
+
+- SCSS (used by GDS, is the de facto standard CSS preprocessor, already using in ETNA)
+- Webpack - compilation of JavaScript and CSS (used by numerous TNA projects already)
+- Babel - will allow us to use ESNext or possibly even TypeScript (although this could go against the lean requirement)
+- Storybook - allow viewing and testing of components (we have already used this elsewhere in TNA)

package/nationalarchives/stories/development/dependencies.mdx

@@ -0,0 +1,9 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/Dependencies" />
+
+# Update Storybook dependencies
+
+```sh
+npx sb upgrade
+```

package/nationalarchives/stories/development/publishing.mdx

@@ -0,0 +1,16 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/Publishing" />
+
+# Publishing a new version
+
+1. Update `version` in `package.json` using [SemVer](https://semver.org/)
+1. Update the CHANGELOG
+1. Run `nvm use` to ensure the correct Node version is used
+1. Run `npm install` to update the `package-lock.json`
+1. Merge all changes to `main` via a pull request
+1. Tag the version with `git tag v1.0.0` (ensure leading `v` and change version number as necessary)
+1. Push the new tag with `git push origin --tags`
+1. Create a [new release on GitHub](https://github.com/nationalarchives/tna-frontend/releases/new) using the tag you just created
+
+Once a release is created, the [publish pipeline](https://github.com/nationalarchives/tna-frontend/blob/main/.github/workflows/npm-publish.yml) will be triggered.

package/nationalarchives/stories/development/relationships.md

@@ -0,0 +1,91 @@
+# Relationship to other resources
+
+## System context
+
+```mermaid
+C4Context
+    Person(dev, "Developer", "TNA developer")
+    System_Ext(github, "GitHub", "Repositories for source files")
+    System_Ext(npm, "NPMJS", "Hosts NodeJS packages")
+    System_Ext(pypi, "PyPi", "Hosts Python packages")
+    Container(app, "Application", "Example application")
+    System_Ext(pypi, "PyPi", "Hosts Python packages")
+
+    Rel(dev, github, "commits to", "git")
+    UpdateRelStyle(dev, github, $offsetX="-30", $offsetY="-30")
+    Rel(github, npm, "publishes to", "npm")
+    Rel(github, pypi, "publishes to", "pip")
+    Rel(app, npm, "consumes", "npm")
+    Rel(app, pypi, "consumes", "pip")
+
+    UpdateLayoutConfig($c4ShapeInRow="2")
+```
+
+## Component diagram
+
+```mermaid
+C4Context
+    Person(dev, "Developer", "TNA developer")
+
+    %% Boundary(developer_machine, "Developer machine", "boundary") {
+    %%     System(docker, "Docker")
+    %% }
+
+    Boundary(github, "GitHub", "boundary") {
+        Boundary(github_jinja, "Jinja templates", "repository") {
+            Container(github_jinja_source, "Jinja templates")
+        }
+
+        Boundary(github_frontend, "Frontend styles", "repository") {
+            Container(github_frontend_source, "Frontend styles", "git repository")
+        }
+
+        Boundary(github_application, "Application", "repository") {
+            Container(github_application_source, "Application source code")
+            Component(github_application_image, "Application docker image", "GitHub image registry")
+        }
+    }
+
+    Boundary(npm, "NPMJS", "boundary") {
+        Component(npm_package, "Frontend styles")
+    }
+
+    Enterprise_Boundary(aws, "TNA AWS", "boundary") {
+        Container(app, "Application")
+    }
+
+    Boundary(pypi, "PyPi", "boundary") {
+        Component(pypi_package, "Jinja templates")
+    }
+
+    Rel(dev, github_frontend_source, "commits to")
+    UpdateRelStyle(dev, github_frontend_source, $offsetX="-80", $offsetY="-80")
+    Rel(github_frontend_source, npm_package, "publishes", "GitHub action")
+    UpdateRelStyle(github_frontend_source, npm_package, $offsetX="-40", $offsetY="-40")
+
+    Rel(dev, github_jinja_source, "commits to")
+    UpdateRelStyle(dev, github_jinja_source, $offsetX="-15", $offsetY="-80")
+    Rel(github_jinja_source, github_frontend_source, "consumes")
+    UpdateRelStyle(github_jinja_source, github_frontend_source, $offsetX="-40", $offsetY="-15")
+    Rel(github_jinja_source, pypi_package, "publishes", "GitHub action")
+    UpdateRelStyle(github_jinja_source, pypi_package, $offsetX="-110", $offsetY="-310")
+
+    Rel(dev, github_application_source, "commits to")
+    UpdateRelStyle(dev, github_application_source, $offsetX="-105", $offsetY="-250")
+    Rel(github_application_source, github_application_image, "creates", "GitHub action")
+    UpdateRelStyle(github_application_source, github_application_image, $offsetX="-90", $offsetY="-20")
+
+    Rel(github_application_image, npm_package, "consumes", "GitHub action")
+    UpdateRelStyle(github_application_image, npm_package, $offsetX="-50", $offsetY="-10")
+    Rel(github_application_image, pypi_package, "consumes", "GitHub action")
+    UpdateRelStyle(github_application_image, pypi_package, $offsetX="-120", $offsetY="-10")
+
+    %% Rel(dev, docker, "uses")
+    %% Rel(docker, npm_package, "consumes")
+    %% Rel(docker, pypi_package, "consumes")
+
+    Rel(app, github_application_image, "consumes")
+    UpdateRelStyle(app, github_application_image, $offsetX="-70", $offsetY="-10")
+
+    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")
+```

package/nationalarchives/stories/development/structure.mdx

@@ -1,7 +1,7 @@
-import { Meta, Primary, Controls, Story } from "@storybook/blocks";
+import { Meta } from "@storybook/blocks";
 
 <Meta title="Development/Structure" />
 
-# Project Structure
+# Project structure
 
 [Technical details]

package/nationalarchives/stories/utilities/heading-groups.stories.js

@@ -0,0 +1,44 @@
+const argTypes = {
+  supertitle: { control: "text" },
+  title: { control: "text" },
+  level: { control: "number", min: 1, max: 6, step: 1 },
+  size: { control: "radio", options: ["m", "l", "xl"] },
+  singleSentence: { control: "boolean" },
+};
+
+export default {
+  title: "Utilities/Typography",
+  argTypes,
+};
+
+const Template = ({
+  supertitle,
+  title,
+  level = 3,
+  size = "l",
+  singleSentence,
+}) =>
+  singleSentence
+    ? `<hgroup class="tna-hgroup tna-hgroup--${size}">
+  <h${level} class="tna-hgroup__title">
+    <span class="tna-hgroup__supertitle">${supertitle}</span>
+    ${title}
+  </h${level}>
+</hgroup>`
+    : `<hgroup class="tna-hgroup tna-hgroup--${size}">
+  <p class="tna-hgroup__supertitle">${supertitle}</p>
+  <h${level} class="tna-hgroup__title">${title}</h${level}>
+</hgroup>`;
+
+export const HeadingGroup = Template.bind({});
+HeadingGroup.args = {
+  supertitle: "The story of",
+  title: "Alice Hawkins",
+  singleSentence: true,
+};
+
+export const HeadingGroupSeparated = Template.bind({});
+HeadingGroupSeparated.args = {
+  supertitle: "Record revealed",
+  title: "The Monteagle Letter",
+};

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

@@ -4,7 +4,7 @@ const argTypes = {
 };
 
 export default {
-  title: "Global styles/Typography",
+  title: "Utilities/Typography",
   argTypes,
 };