@nationalarchives/frontend 0.1.23-prerelease → 0.1.24-prerelease

package/nationalarchives/stories/development/contributing.mdx

@@ -1,32 +0,0 @@
-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`, `[myComponent].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")`
-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` - Simply includes `@use "myComponent";` so we can include this directory within SASS and have it reference the styles in `[myComponent].scss`
-- `[myComponent].scss` - this file gets built as a standalone file as well as being included in all styles and is 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 add the JavaScript class to check for
-1. If your component uses JavaScript, ensure you add interaction tests using `@storybook/testing-library`

package/nationalarchives/stories/development/cookies.mdx

@@ -1,82 +0,0 @@
-import { Meta } from "@storybook/blocks";
-import { Mermaid } from 'mdx-mermaid/Mermaid';
-
-<Meta title="Development/Cookies" />
-
-# Cookies handling
-
-The principles of cookie handling are:
-
-- Create cookies on the client side (apart from session cookies)
-- Update cookies on the client side (apart from session cookies)
-- Reject by default (don't assume acceptance and don't add tracking until after they agree)
-
-## Policies
-
-As standard we should use at least these three classes of cookies:
-
-- `essential` - we don't need to ask permission for these
-- `usage` - analytics, tracking, data gathering
-- `settings` - configured options for the site (e.g. default results view or static light/dark mode)
-
-## Process
-
-### First visit
-
-<Mermaid chart={`sequenceDiagram
-    User->>Browser: Request page
-    Browser->>Server: HTTP request with no cookies
-    Server->>Browser: Rendered HTML with cookie banner and no analytics
-    Browser->>User: Accept cookies?
-    alt Accept
-        User->>Browser: Accept cookies
-        Browser->>Browser: Create cookie policy with all accepted
-        Browser->>Browser: Add analytics code with JavaScript
-    else Reject
-        User->>Browser: Reject cookies
-        Browser->>Browser: Create cookie policy with all rejected
-    end
-    opt Next request
-        User->>Browser: Request page
-        Browser->>Server: HTTP request with cookie policy
-        Server->>Browser: Rendered HTML with analytics but no cookie banner
-    end
-`} />
-
-### Repeat visit
-
-<Mermaid chart={`sequenceDiagram
-    User->>Browser: Request page
-    Browser->>Server: HTTP request with cookie policy
-    Server->>Browser: Rendered HTML with analytics but no cookie banner
-`} />
-
-## Cookie library
-
-When you load in the tna-frontend JavaScript, it comes with a [cookie library](https://github.com/nationalarchives/tna-frontend/blob/main/src/nationalarchives/lib/cookies.mjs).
-
-This is loaded into the `window` object as `TNAFrontend.Cookies`:
-
-```JavaScript
-// Initialise a new Cookie instance
-const cookies = new TNAFrontend.Cookies();
-
-// Log all the cookies to the console
-console.log(cookies.all);
-```
-
-### Functions
-
-- `cookies.all` - Returns all the cookies
-- `cookies.exists(key)` - Returns `true` if a cookie exists with the name `key`
-- `cookies.hasValue(key, value)` - Returns `true` if the cookie with the name `key` is equal to `value`
-- `cookies.get(key)` - Returns the cookie with the name `key`
-- `cookies.set(key, value, maxAge, path)` - Set a cookie (max age default is one year, default path is `/`)
-- `cookies.delete(key)` - Deletes the cookie with the name `key`
-- `cookies.allPolicies` - Returns all the cookie policies
-- `cookies.acceptPolicy(policy)` - Accepts the policy with the name `policy`
-- `cookies.rejectPolicy(policy)` - Rejects the policy with the name `policy`
-- `cookies.setPolicy(policy, accepted)` - Accepts or rejects the policy with the name `policy` depending on the value of `accepted`
-- `cookies.acceptAllPolicies()` - Accepts all policies
-- `cookies.rejectAllPolicies()` - Rejects all policies
-- `cookies.isPolicyAccepted(policy)` - Returns `true` or `false` depending on whether the policy has been accepted

package/nationalarchives/stories/development/publishing.mdx

@@ -1,15 +0,0 @@
-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. Wait for the CI to pass
-1. Create a [new release on GitHub](https://github.com/nationalarchives/tna-frontend/releases/new) and add a new tag in the format `v1.0.0` (ensure leading `v` and change version number as necessary)
-
-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/structure.mdx

@@ -1,88 +0,0 @@
-import { Meta } from "@storybook/blocks";
-
-<Meta title="Development/Structure" />
-
-# Structure
-
-The layers of the TNA frontend SCSS library is built as:
-
-1. [Variables](#variables)
-1. [Tools](#tools)
-1. [Libraries](#libraries)/[Utilities](#utilities)
-1. [Components](#components)
-1. [Overrides](#overrides)
-
-## Variables
-
-TNA frontend variables are defined in `src/nationalarchives/variables`.
-
-Lots of variables can be modified but some are fixed, such as our brand colours.
-
-An example fixed variable is `$relative-1rem-px` where we set the value of `1rem` to `16px` which makes it easier to define widths as a function of `1rem` as we mostly work on a 4px grid:
-
-| Pixels | REM         |
-| ------ | ----------- |
-| `1px`  | `0.0625rem` |
-| `2px`  | `0.125rem`  |
-| `4px`  | `0.25rem`   |
-| `8px`  | `0.5rem`    |
-| `16px` | `1rem`      |
-| `32px` | `2rem`      |
-| `64px` | `4rem`      |
-
-An example of a variable that can be modified is `$body-font-size-px` which we set to `18px` by default. This font size might not be right for all services so we have allowed it to be modified.
-
-## Tools
-
-The tools provided are reusable `@mixin` and `@function` blocks to make writing styles easier. They are defined in `src/nationalarchives/tools`.
-
-Tools rely directly on variables and can be used throughout the frontend library.
-
-As an exmaple, `colour-font()` will apply a font colour in a way that should work for all browsers and takes into consideration the light/dark theme used.
-
-## Libraries
-
-The libraries in `src/nationalarchives/lib` are a mix of third party libraries as well as some TNA ones.
-
-They can join up tools to make larger, more useful elements.
-
-## Utilities
-
-The utilities in `src/nationalarchives/utilities` are some global styles that aren't associated with a specific component.
-
-This layer is where we define some general purpose elements such as:
-
-- The `tna-template` and `tna-template__body` elements
-- Headings
-- Lists
-- Chips
-- `<p>` elements
-- General media elements like `<img>`, `<svg>`, `<picture>`, `<video>` and `<canvas>`
-- Columns
-- General form elements
-
-These elements all still adhere to the [BEM methodology](https://getbem.com/).
-
-Utilities should not implement any `!important` rules.
-
-## Components
-
-The most prominent layer of styling, the components in `src/nationalarchives/components` should use the tools already defined.
-
-Components shouldn't use variables directly. They shouldn't use static values for colour unless the colour of that component will never change, for example the message component which is always yellow.
-
-Some components may use utilities such as headings. Where these styles have already been defined, they should not be redefined. The heading in a cookie banner should use the existing `tna-heading` and `tna-heading--m` styles that already exist rather than implimenting its own.
-
-Components should not implement any `!important` rules. There are exceptions such as the skip link that needs to be visually hidden in a way that it is still available for someone navigating a site with a keyboard.
-
-Components should not care about the context or layout within which they are used. As an example, a breadcrumb *could* be placed within a card or a footer element although in reality we wouldn't allow this.
-
-## Overrides
-
-Overrides start with `tna-!--` and can only be used in HTML classes. They have `!important` rules.
-
-Examples of overrides are:
-
-- Spacing (margin, padding etc.)
-- No focus style (`.tna-!--no-focus-style`) for items such as the target element of a skip link
-- Visibly hidden content (used to add extra descriptions which appear for screenreaders only)

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

@@ -1,9 +0,0 @@
-import { Meta } from "@storybook/blocks";
-
-<Meta title="Development/Using/Compiled" />
-
-# Using the compiled files
-
-Each release (as of `v0.1.21-prerelease`) should contain a ZIP of the package.
-
-Find the release you want on the `tna-frontend` [releases page](https://github.com/nationalarchives/tna-frontend/releases) and download the package from the "Assets" dropdown.

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

@@ -1,53 +0,0 @@
-import { Meta } from "@storybook/blocks";
-
-<Meta title="Development/Using/Hosted" />
-
-# Using with a hosted solution
-
-The `@nationalarchives/frontend` package is available on [jsdelivr.com](https://www.jsdelivr.com/package/npm/@nationalarchives/frontend).
-
-While you can use the CSS and JavaScript from there, the font files which includes the icon font will have to be hosted from your web application.
-
-As a result, **using a hosted solution is not the preferred method for using the `tna-frontend` library**.
-
-## All components and styles
-
-Include the CSS in the `<head>` element of your page:
-
-```html
-<link href="https://cdn.jsdelivr.net/npm/@nationalarchives/frontend@0.1.18-prerelease/nationalarchives/all.css" rel="stylesheet" integrity="sha384-6Egfw6aX1Jrwuf+APn+BMPswroudkIQ6StU095OPkNCKLEzj7ksWGmYxjend8P7g" crossorigin="anonymous">
-```
-
-### JavaScript
-
-Add the JavaScript to the end of your page just before your closing `</body>` tag:
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/@nationalarchives/frontend@0.1.18-prerelease/nationalarchives/all.js" integrity="sha384-sBkiMlxl9svXopGxNSMVAdALjzyvh6sQHp+21PE3LGfTxAEbG4EIpK" crossorigin="anonymous"></script>
-<script>
-  // Initialise all TNA components
-  window.TNAFrontend.initAll();
-</script>
-```
-
-...or use the module syntax:
-
-```
-<script type="module">
-  import { initAll } from "https://cdn.jsdelivr.net/npm/@nationalarchives/frontend@0.1.18-prerelease/nationalarchives/all.js";
-  initAll();
-</script>
-```
-
-## Specific components
-
-```html
-<link href="https://cdn.jsdelivr.net/npm/@nationalarchives/frontend@0.1.18-prerelease/nationalarchives/components/tabs.css" rel="stylesheet" integrity="sha384-hkx4svJn1A7pWYlzaDRMmtIBBijZdEop+M1Y/H4Hdg8aAqZRJHG56RokLk/eqJYl" crossorigin="anonymous">
-```
-
-### JavaScript
-
-```html
-<!-- JavaScript for a single component -->
-<script src="https://cdn.jsdelivr.net/npm/@nationalarchives/frontend@0.1.18-prerelease/nationalarchives/components/tabs.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
-```

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

@@ -1,59 +0,0 @@
-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`