@nationalarchives/frontend 0.1.9-prerelease → 0.1.11-prerelease

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

@@ -0,0 +1,302 @@
+import Tabs from "./template.njk";
+import macroOptions from "./macro-options.json";
+import { expect } from "@storybook/jest";
+import { within, userEvent } from "@storybook/testing-library";
+
+const argTypes = {
+  title: { control: "text" },
+  items: { control: "array" },
+  sticky: { control: "boolean" },
+  classes: { control: "text" },
+  attributes: { control: "object" },
+};
+
+Object.keys(argTypes).forEach((argType) => {
+  argTypes[argType].description = macroOptions.find(
+    (option) => option.name === argType,
+  )?.description;
+});
+
+export default {
+  title: "Work in progress/Components/Tabs",
+  argTypes,
+};
+
+const Template = ({ title, items, sticky, classes, attributes }) => {
+  return Tabs({
+    params: {
+      title,
+      items,
+      sticky,
+      classes,
+      attributes,
+    },
+  });
+};
+
+export const Standard = Template.bind({});
+Standard.args = {
+  title: "Example tabs",
+  items: [
+    {
+      id: "unique-id-a",
+      title: "Alpha section",
+      body: "<h2>Alpha title</h2><p>Lorem ipsum</p>",
+    },
+    {
+      id: "unique-id-b",
+      title: "Beta section",
+      body: "<h2>Beta title</h2><p>Lorem ipsum</p>",
+    },
+    {
+      id: "unique-id-c",
+      title: "Gamma section",
+      body: "<h2>Gamma title</h2><p>Lorem ipsum</p>",
+    },
+  ],
+  classes: "tna-tabs--demo",
+};
+
+export const Test = Template.bind({});
+Test.args = {
+  title: "Example tabs",
+  items: [
+    {
+      id: "unique-id-a",
+      title: "Alpha section",
+      body: "<h2>Alpha title</h2><p>Lorem ipsum</p>",
+    },
+    {
+      id: "unique-id-b",
+      title: "Beta section",
+      body: "<h2>Beta title</h2><p>Lorem ipsum</p>",
+    },
+    {
+      id: "unique-id-c",
+      title: "Gamma section",
+      body: "<h2>Gamma title</h2><p>Lorem ipsum</p>",
+    },
+  ],
+  classes: "tna-tabs--demo",
+};
+
+Test.play = async ({ args, canvasElement, step }) => {
+  const canvas = within(canvasElement);
+
+  const tablist = canvas.getByRole("tablist");
+  const [buttonA, buttonB, buttonC] = args.items.map((item) =>
+    canvas.getByText(item.title),
+  );
+  const [sectionA, sectionB, sectionC] = args.items.map((item) =>
+    canvasElement.querySelector(`#${item.id}`),
+  );
+
+  const expectButtonToBeCurrent = async (button) => {
+    await expect(button).toHaveAttribute("tabindex", "0");
+    await expect(button).toHaveAttribute("aria-selected", "true");
+    await expect(button).toHaveFocus();
+  };
+
+  const expectButtonNotToBeCurrent = async (button) => {
+    await expect(button).toHaveAttribute("tabindex", "-1");
+    await expect(button).toHaveAttribute("aria-selected", "false");
+  };
+
+  const expectSectionToBeCurrent = async (section) => {
+    await expect(section).toBeVisible();
+    await expect(section).toHaveAttribute("tabindex", "0");
+  };
+
+  const expectSectionNotToBeCurrent = async (section) => {
+    await expect(section).not.toBeVisible();
+    await expect(section).toHaveAttribute("tabindex", "-1");
+  };
+
+  const expectButtonAndSectionAToBeCurrent = async (section) => {
+    await step("Test tab buttons", async () => {
+      await expectButtonToBeCurrent(buttonA);
+      await expectButtonNotToBeCurrent(buttonB);
+      await expectButtonNotToBeCurrent(buttonC);
+    });
+
+    await step("Test tab sections", async () => {
+      await expectSectionToBeCurrent(sectionA);
+      await expectSectionNotToBeCurrent(sectionB);
+      await expectSectionNotToBeCurrent(sectionC);
+    });
+  };
+
+  const expectButtonAndSectionBToBeCurrent = async (section) => {
+    await step("Test tab buttons", async () => {
+      await expectButtonNotToBeCurrent(buttonA);
+      await expectButtonToBeCurrent(buttonB);
+      await expectButtonNotToBeCurrent(buttonC);
+    });
+
+    await step("Test tab sections", async () => {
+      await expectSectionNotToBeCurrent(sectionA);
+      await expectSectionToBeCurrent(sectionB);
+      await expectSectionNotToBeCurrent(sectionC);
+    });
+  };
+
+  const expectButtonAndSectionCToBeCurrent = async (section) => {
+    await step("Test tab buttons", async () => {
+      await expectButtonNotToBeCurrent(buttonA);
+      await expectButtonNotToBeCurrent(buttonB);
+      await expectButtonToBeCurrent(buttonC);
+    });
+
+    await step("Test tab sections", async () => {
+      await expectSectionNotToBeCurrent(sectionA);
+      await expectSectionNotToBeCurrent(sectionB);
+      await expectSectionToBeCurrent(sectionC);
+    });
+  };
+
+  await step("Initial load", async () => {
+    await step("Test tablist", async () => {
+      await expect(tablist).toBeDefined();
+      await expect(tablist).toBeVisible();
+    });
+
+    await step("Test tab buttons", async () => {
+      await step("First tab button", async () => {
+        await expect(buttonA).toBeVisible();
+        await expect(buttonA).toHaveAttribute("id", `${args.items[0].id}-tab`);
+        await expect(buttonA).toHaveAttribute("role", "tab");
+        await expect(buttonA).toHaveAttribute("tabindex", "0");
+        await expect(buttonA).toHaveAttribute("aria-selected", "true");
+        await expect(buttonA).toHaveAttribute(
+          "aria-controls",
+          args.items[0].id,
+        );
+      });
+
+      await step("Second tab button", async () => {
+        await expect(buttonB).toBeVisible();
+        await expect(buttonB).toHaveAttribute("id", `${args.items[1].id}-tab`);
+        await expect(buttonB).toHaveAttribute("role", "tab");
+        await expect(buttonB).toHaveAttribute("tabindex", "-1");
+        await expect(buttonB).toHaveAttribute("aria-selected", "false");
+        await expect(buttonB).toHaveAttribute(
+          "aria-controls",
+          args.items[1].id,
+        );
+      });
+
+      await step("Third tab button", async () => {
+        await expect(buttonC).toBeVisible();
+        await expect(buttonC).toHaveAttribute("id", `${args.items[2].id}-tab`);
+        await expect(buttonC).toHaveAttribute("role", "tab");
+        await expect(buttonC).toHaveAttribute("tabindex", "-1");
+        await expect(buttonC).toHaveAttribute("aria-selected", "false");
+        await expect(buttonC).toHaveAttribute(
+          "aria-controls",
+          args.items[2].id,
+        );
+      });
+    });
+
+    await step("Test tab sections", async () => {
+      await expect(sectionA).toBeVisible();
+      await expect(sectionA).toHaveAttribute("id", args.items[0].id);
+      await expect(sectionA).toHaveAttribute("role", "tabpanel");
+      await expect(sectionA).toHaveAttribute(
+        "aria-labelledby",
+        `${args.items[0].id}-tab`,
+      );
+      await expect(sectionA).toHaveAttribute("tabindex", "0");
+
+      await expect(sectionB).not.toBeVisible();
+      await expect(sectionB).toHaveAttribute("id", args.items[1].id);
+      await expect(sectionB).toHaveAttribute("role", "tabpanel");
+      await expect(sectionB).toHaveAttribute(
+        "aria-labelledby",
+        `${args.items[1].id}-tab`,
+      );
+      await expect(sectionB).toHaveAttribute("tabindex", "0");
+
+      await expect(sectionC).not.toBeVisible();
+      await expect(sectionC).toHaveAttribute("id", args.items[2].id);
+      await expect(sectionC).toHaveAttribute("role", "tabpanel");
+      await expect(sectionC).toHaveAttribute(
+        "aria-labelledby",
+        `${args.items[2].id}-tab`,
+      );
+      await expect(sectionC).toHaveAttribute("tabindex", "0");
+    });
+  });
+
+  await userEvent.click(buttonA);
+
+  await step("First tab (already selected)", async () => {
+    await userEvent.click(buttonA);
+    await expectButtonAndSectionAToBeCurrent();
+  });
+
+  await step("Second tab", async () => {
+    await userEvent.click(buttonB);
+    await expectButtonAndSectionBToBeCurrent();
+  });
+
+  await step("Third tab", async () => {
+    await userEvent.click(buttonC);
+    await expectButtonAndSectionCToBeCurrent();
+  });
+
+  await step("First tab", async () => {
+    await userEvent.click(buttonA);
+    await expectButtonAndSectionAToBeCurrent();
+  });
+
+  await step("Keyboard interaciton", async () => {
+    await step("Left/right", async () => {
+      await userEvent.click(buttonA);
+      await expectButtonAndSectionAToBeCurrent();
+
+      await userEvent.keyboard("[ArrowRight]");
+      await expectButtonAndSectionBToBeCurrent();
+
+      await userEvent.keyboard("[ArrowRight]");
+      await expectButtonAndSectionCToBeCurrent();
+
+      await userEvent.keyboard("[ArrowRight]");
+      await expectButtonAndSectionAToBeCurrent();
+
+      await userEvent.keyboard("[ArrowRight]");
+      await expectButtonAndSectionBToBeCurrent();
+
+      await userEvent.keyboard("[ArrowLeft]");
+      await expectButtonAndSectionAToBeCurrent();
+
+      await userEvent.keyboard("[ArrowLeft]");
+      await expectButtonAndSectionCToBeCurrent();
+
+      await userEvent.keyboard("[ArrowLeft]");
+      await expectButtonAndSectionBToBeCurrent();
+
+      await userEvent.keyboard("[ArrowLeft]");
+      await expectButtonAndSectionAToBeCurrent();
+    });
+
+    await step("Home/end", async () => {
+      await userEvent.click(buttonA);
+      await expectButtonAndSectionAToBeCurrent();
+
+      await userEvent.keyboard("[Home]");
+      await expectButtonAndSectionAToBeCurrent();
+
+      await userEvent.keyboard("[End]");
+      await expectButtonAndSectionCToBeCurrent();
+
+      await userEvent.keyboard("[End]");
+      await expectButtonAndSectionCToBeCurrent();
+
+      await userEvent.keyboard("[Home]");
+      await expectButtonAndSectionAToBeCurrent();
+    });
+
+    buttonA.blur();
+  });
+};

package/nationalarchives/components/tabs/template.njk

@@ -0,0 +1,20 @@
+{%- set containerClasses = [params.classes] if params.classes else [] -%}
+{%- if params.sticky -%}
+  {%- set containerClasses = containerClasses.concat('tna-tabs--sticky') -%}
+{%- endif -%}
+<div class="tna-tabs {{ containerClasses | join(' ') }}" data-module="tna-tabs" {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+  <ul class="tna-tabs__list" aria-label="{{ params.title }}">
+  {% for item in params.items %}
+    <li class="tna-tabs__list-item">
+      <a href="#{{ item.id }}" class="tna-tabs__list-item-link" id="{{ item.id }}-tab">{{ item.title }}</a>
+    </li>
+  {% endfor %}
+  </ul>
+  <div class="tna-tabs__items">
+  {% for item in params.items %}
+    <section id="{{ item.id }}" class="tna-tabs__item">
+      {{ item.body | safe }}
+    </section>
+  {% endfor %}
+  </div>
+</div>

package/nationalarchives/patterns/_index.scss

@@ -0,0 +1 @@
+@forward "featured-collection/index";

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

@@ -0,0 +1,13 @@
+@use "../../variables/colour" as colourVars;
+
+.tna-featured-collection {
+  padding-top: 2rem;
+  padding-bottom: 2rem;
+
+  background-color: colourVars.$tna-cream;
+
+  .tna-card {
+    margin-top: 1rem;
+    margin-bottom: 1rem;
+  }
+}

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

@@ -0,0 +1,35 @@
+import FeaturedCollection from "./template.njk";
+import macroOptions from "./macro-options.json";
+
+const argTypes = {
+  heading: { 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: "Experimental/Patterns/Featured collection",
+  argTypes,
+};
+
+const Template = ({ heading, classes, attributes }) => {
+  return FeaturedCollection({
+    params: {
+      heading,
+      classes,
+      attributes,
+    },
+  });
+};
+
+export const Standard = Template.bind({});
+Standard.args = {
+  heading: "Records from the collection",
+  classes: "tna-featured-collection--demo",
+};

package/nationalarchives/patterns/featured-collection/macro-options.json

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

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

@@ -0,0 +1,3 @@
+{% macro tnaFeaturedCollection(params) %}
+  {%- include "nationalarchives/patterns/featured-collection/template.njk" -%}
+{% endmacro %}

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

@@ -0,0 +1,96 @@
+{% from "nationalarchives/components/grid/macro.njk" import tnaGrid %}
+{% from "nationalarchives/components/card/macro.njk" import tnaCard %}
+
+{% set exampleCard = {
+  heading: {
+    title: "Card title",
+    level: 3,
+    size: "m",
+    singleSentence: true
+  },
+  href: "#",
+  image: {
+    src: "https://picsum.photos/id/29/640/360",
+    alt: "A placeholder image"
+  },
+  body: "<p>Card body</p>"
+} %}
+
+{%- set containerClasses = [params.classes] if params.classes else [] -%}
+{%- set containerClasses = containerClasses.concat('tna-featured-collection') -%}
+
+{{ tnaGrid({
+  columns: [
+    {
+      width: "full",
+      widthMedium: "full",
+      widthSmall: "full",
+      widthTiny: "full",
+      html: "<h2 class=\"tna-heading\">" + params.heading + "</h2>"
+    },
+    {
+      width: "1-2",
+      widthMedium: "2-3",
+      widthSmall: "1-2",
+      widthTiny: "full",
+      html: tnaCard({
+        heading: {
+          title: "Card title",
+          level: 3,
+          size: "m",
+          singleSentence: true
+        },
+        href: "#",
+        image: {
+          src: "https://picsum.photos/id/29/640/360",
+          alt: "A placeholder image",
+          label: "Feature"
+        },
+        body: "<p>Card body</p>"
+      })
+    },
+    {
+      width: "1-2",
+      widthMedium: "1-3",
+      widthSmall: "1-2",
+      widthTiny: "full",
+      html: tnaGrid({
+        columns: [
+          {
+            width: "1-2",
+            widthMedium: "full",
+            widthSmall: "full",
+            widthTiny: "full",
+            html: tnaCard(exampleCard)
+          },
+          {
+            width: "1-2",
+            widthMedium: "full",
+            widthSmall: "full",
+            widthTiny: "full",
+            html: tnaCard(exampleCard)
+          },
+          {
+            width: "1-2",
+            widthMedium: "full",
+            widthSmall: "full",
+            widthTiny: "full",
+            html: tnaCard(exampleCard)
+          },
+          {
+            width: "1-2",
+            widthMedium: "full",
+            widthSmall: "full",
+            widthTiny: "full",
+            html: tnaCard(exampleCard)
+          }
+        ],
+        noPadding: true
+      }),
+      noPadding: true
+    }
+  ],
+  htmlElement: "section",
+  classes: containerClasses | join(' '),
+  attributes: params.attributes
+}) }}

package/nationalarchives/stories/development/contributing.mdx

@@ -0,0 +1,39 @@
+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
+1. Add the component import and macro to the prototype kit test in `.github/workflows/ci.yml`
+
+### 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