@nationalarchives/frontend 0.1.20-prerelease → 0.1.22-prerelease

package/nationalarchives/stories/development/contributing.mdx

@@ -30,13 +30,3 @@ import { Meta } from "@storybook/blocks";
 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`
-
-### Best practices
-
-- [HTML standards](https://nationalarchives.github.io/developer-handbook/technology/html/)
-- [JavaScript standards](https://nationalarchives.github.io/developer-handbook/technology/javascript/)
-- [CSS standards](https://nationalarchives.github.io/developer-handbook/technology/css/)
-
-## Updating a component
-
-[TODO]

package/nationalarchives/stories/development/cookies.mdx

@@ -0,0 +1,82 @@
+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/structure.mdx

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

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

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

@@ -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`