@nationalarchives/frontend 0.21.0 → 0.23.0

package/nationalarchives/font-awesome.scss

@@ -1,6 +1,7 @@
 @use "variables/assets";
-
-$fa-font-path: assets.$fa-font-path;
-@import "lib/font-awesome/fontawesome";
-@import "lib/font-awesome/solid";
-@import "lib/font-awesome/brands";
+@use "lib/font-awesome/variables" with (
+  $font-path: assets.$fa-font-path
+);
+@use "lib/font-awesome/fontawesome";
+@use "lib/font-awesome/solid";
+@use "lib/font-awesome/brands";

package/nationalarchives/lib/analytics-helpers.mjs

@@ -26,23 +26,16 @@ const getXPathTo = ($element) => {
   }
 };
 
-const includesAny = (arr, values) => values.some((v) => arr.includes(v));
-
-const getClosestHeading = ($element) => {
+const getClosestElement = ($startingElement, matchingElementSelectors) => {
   let heading = "";
-  let $search = $element;
+  let $search = $startingElement;
   do {
     while ($search.previousElementSibling) {
       $search = $search.previousElementSibling;
       if (
-        ["h1", "h2", "h3", "h4", "h5", "h6"].includes($search.tagName) ||
-        ($search.classList.length &&
-          includesAny(Array.from($search.classList), [
-            "tna-heading-xl",
-            "tna-heading-l",
-            "tna-heading-m",
-            "tna-heading-s",
-          ]))
+        matchingElementSelectors.some((matchingElementSelector) =>
+          $search.matches(matchingElementSelector),
+        )
       ) {
         heading = $search.innerText;
         break;
@@ -53,6 +46,9 @@ const getClosestHeading = ($element) => {
   return heading;
 };
 
+const getClosestHeading = ($element) =>
+  getClosestElement($element, ["h1", "h2", "h3", "h4", "h5", "h6"]);
+
 const valueGetters = {
   text: ($el) => $el.innerText.replace(/\n/g, " "),
   html: ($el) => $el.innerHTML,
@@ -71,4 +67,4 @@ const valueGetters = {
   xpath: ($el) => getXPathTo($el.target),
 };
 
-export { getXPathTo, getClosestHeading, valueGetters };
+export { getXPathTo, getClosestElement, getClosestHeading, valueGetters };

package/nationalarchives/lib/cookies.mjs

@@ -4,14 +4,23 @@ window.TNAFrontendCookieEvents = window.TNAFrontendCookieEvents || null;
 export class CookieEventHandler {
   events = {};
   oneTimeEvents = {};
+  debug = false;
 
-  constructor() {
+  constructor(debug = false) {
+    this.debug = debug;
     if (window.TNAFrontendCookieEvents) {
+      this.log("Using existing TNAFrontendCookieEvents instance");
       return window.TNAFrontendCookieEvents;
     }
     window.TNAFrontendCookieEvents = this;
   }
 
+  log(...args) {
+    if (this.debug) {
+      console.log("[TNA Frontend Cookie Events]", ...args);
+    }
+  }
+
   /**
    * Add an event listener.
    * @param {String} event - The event to add a listener for.
@@ -34,11 +43,13 @@ export class CookieEventHandler {
   /** @protected */
   trigger(event, data = {}) {
     if (Object.hasOwn(this.events, event)) {
+      this.log(`Triggering event: ${event}`, data);
       this.events[event].forEach((eventToTrigger) =>
         eventToTrigger.call(this, data),
       );
     }
     if (Object.hasOwn(this.oneTimeEvents, event)) {
+      this.log(`Triggering one-time event: ${event}`, data);
       for (let i = this.oneTimeEvents[event].length - 1; i >= 0; i--) {
         const eventToTrigger = this.oneTimeEvents[event][i];
         eventToTrigger.call(this, data);
@@ -70,7 +81,9 @@ export default class Cookies {
   /** @protected */
   defaultAge = null;
   /** @protected */
-  completePoliciesOnInit = false;
+  policiesCorrectOnInit = false;
+  /** @protected */
+  debug = document.documentElement.dataset.tnaFrontendDebug === "true";
 
   /**
    * Create a cookie handler.
@@ -78,8 +91,8 @@ export default class Cookies {
    * @param {String} [options.path] - The domain to register the cookie with.
    * @param {Boolean} [options.secure] - Only set cookie in HTTPS environments.
    * @param {String} [options.policiesKey] - The name of the cookie.
-   * @param {String} [options.newInstance=false] - Create a fresh instance of the cookie class.
    * @param {Number} [options.defaultAge] - The default age of non-session cookies.
+   * @param {String} [options.newInstance=false] - Create a fresh instance of the cookie class.
    * @param {Boolean} [options.noInit=false] - Don't initialise a blank cookie policy.
    */
   constructor(options = {}) {
@@ -88,8 +101,8 @@ export default class Cookies {
       defaultPath,
       secure,
       policiesKey,
-      newInstance = false,
       defaultAge,
+      newInstance = false,
       noInit = false,
     } = options;
     if (!newInstance && window.TNAFrontendCookies) {
@@ -97,7 +110,8 @@ export default class Cookies {
     }
     if (defaultDomain === undefined) {
       this.defaultDomain =
-        document.documentElement.dataset.tnaCookiesDomain || "";
+        document.documentElement.dataset.tnaCookiesDomain ||
+        window.location.hostname;
     } else {
       this.defaultDomain = defaultDomain;
     }
@@ -126,28 +140,42 @@ export default class Cookies {
     } else {
       this.defaultAge = defaultAge;
     }
-    this.events = new CookieEventHandler();
-    this.completePoliciesOnInit =
+    this.events = new CookieEventHandler(this.debug);
+    this.policiesCorrectOnInit =
       Object.keys(this.policies).length === tnaCookiePolicies.length &&
       tnaCookiePolicies.every(
         (policy) =>
           Object.keys(this.policies).includes(policy) &&
           typeof this.policies[policy] === "boolean",
       );
-    if (!this.completePoliciesOnInit && !noInit) {
+    if (!this.policiesCorrectOnInit && !noInit) {
       this.init();
     }
-    window.TNAFrontendCookies = this;
+    this.log({
+      defaultDomain: this.defaultDomain,
+      defaultPath: this.defaultPath,
+      secure: this.secure,
+      policiesKey: this.policiesKey,
+      defaultAge: this.defaultAge,
+      policiesCorrectOnInit: this.policiesCorrectOnInit,
+    });
+    if (!newInstance && !window.TNAFrontendCookies) {
+      window.TNAFrontendCookies = this;
+    }
   }
 
   /** @protected */
   init() {
     const existingPolicies = this.policies;
+    this.log("Existing policies on init:", existingPolicies);
     const filteredExistingPolicies = Object.fromEntries(
       Object.keys(existingPolicies)
         .filter((policy) => tnaCookiePolicies.includes(policy))
         .map((policy) => [policy, existingPolicies[policy]]),
     );
+    if (Object.keys(filteredExistingPolicies).length > 0) {
+      this.log("Filtered existing policies:", filteredExistingPolicies);
+    }
     this.savePolicies({
       usage: false,
       settings: false,
@@ -157,7 +185,14 @@ export default class Cookies {
     });
   }
 
+  log(...args) {
+    if (this.debug) {
+      console.log("[TNA Frontend Cookies]", ...args, this.all);
+    }
+  }
+
   destroyInstance() {
+    this.log("Destroying TNAFrontendCookies instance");
     window.TNAFrontendCookies = null;
   }
 
@@ -238,12 +273,21 @@ export default class Cookies {
     if (!key) {
       return;
     }
-    const cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value)};${
-      domain ? ` domain=${domain}; ` : ""
-    } samesite=${sameSite}; path=${path}${!session ? `; max-age=${maxAge}` : ""}${
+    const cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value)}; domain=${domain}; samesite=${sameSite}; path=${path}${!session ? `; max-age=${maxAge}` : ""}${
       secure ? "; secure" : ""
     }`;
     document.cookie = cookie;
+    this.log("Set cookie:", {
+      key,
+      value,
+      maxAge,
+      path,
+      sameSite,
+      domain,
+      secure,
+      session,
+      cookie,
+    });
     this.events.trigger("setCookie", {
       key,
       value,
@@ -262,19 +306,21 @@ export default class Cookies {
    * @param {String} key - The cookie name.
    * @param {String} [path=/] - The path to the cookie is registered on.
    */
-  delete(key, path = "/", domain = null) {
+  delete(key, path = "/", domain = this.defaultDomain) {
     const options = { maxAge: -1, path, domain: domain || undefined };
     this.set(key, "", options);
+    this.log("Deleted cookie:", { key, path, domain, ...options });
     this.events.trigger("deleteCookie", { key, ...options });
   }
 
   /**
    * Delete all cookies.
    */
-  deleteAll(path = "/", domain = null) {
+  deleteAll(path = "/", domain = this.defaultDomain) {
     Object.keys(this.all).forEach((cookie) => {
       this.delete(cookie, path, domain);
     });
+    this.log("Deleted all cookies", { path, domain });
     this.events.trigger("deleteAllCookies", { path, domain });
   }
 
@@ -283,6 +329,7 @@ export default class Cookies {
    * @param {String} policy - The name of the policy.
    */
   acceptPolicy(policy) {
+    this.log("Accepting policy:", policy);
     this.setPolicy(policy, true);
     this.events.trigger("acceptPolicy", policy);
     this.events.trigger("changePolicy", { [policy]: true });
@@ -293,6 +340,7 @@ export default class Cookies {
    * @param {String} policy - The name of the policy.
    */
   rejectPolicy(policy) {
+    this.log("Rejecting policy:", policy);
     this.setPolicy(policy, false);
     this.events.trigger("rejectPolicy", policy);
     this.events.trigger("changePolicy", { [policy]: false });
@@ -305,8 +353,10 @@ export default class Cookies {
    */
   setPolicy(policy, accepted) {
     if (policy === "essential") {
+      this.log("Cannot change essential policy, it is always accepted.");
       return;
     }
+    this.log(`Setting policy ${policy} to ${accepted}`);
     this.savePolicies({
       ...this.policies,
       [policy]: accepted,
@@ -319,6 +369,7 @@ export default class Cookies {
    * Accept all the cookie policies.
    */
   acceptAllPolicies() {
+    this.log("Accepting all policies");
     const allPolicies = Object.fromEntries(
       Object.keys(this.policies).map((k) => [k.toLowerCase(), true]),
     );
@@ -331,6 +382,7 @@ export default class Cookies {
    * Reject all the cookie policies.
    */
   rejectAllPolicies() {
+    this.log("Rejecting all policies");
     const allPolicies = {
       ...Object.fromEntries(
         Object.keys(this.policies).map((k) => [k.toLowerCase(), false]),
@@ -347,6 +399,7 @@ export default class Cookies {
    * @param {object} policies - The policies to commit.
    */
   savePolicies(policies) {
+    this.log("Saving policies:", policies);
     this.set(this.policiesKey, JSON.stringify(policies));
   }
 
@@ -367,6 +420,7 @@ export default class Cookies {
    * @param {Function} callback - The callback function to call when the event is triggered.
    */
   on(event, callback) {
+    this.log(`Adding event listener for: ${event}`);
     this.events.on(event, callback);
   }
 
@@ -376,6 +430,7 @@ export default class Cookies {
    * @param {Function} callback - The callback function to call when the event is triggered.
    */
   once(event, callback) {
+    this.log(`Adding one-time event listener for: ${event}`);
     this.events.once(event, callback);
   }
 }

package/nationalarchives/lib/font-awesome/_animated.scss

@@ -1,183 +1,178 @@
 // animating icons
 // --------------------------
+@use "variables" as v;
 
-.#{$fa-css-prefix}-beat {
-  animation-name: #{$fa-css-prefix}-beat;
-  animation-delay: var(--#{$fa-css-prefix}-animation-delay, 0s);
-  animation-direction: var(--#{$fa-css-prefix}-animation-direction, normal);
-  animation-duration: var(--#{$fa-css-prefix}-animation-duration, 1s);
+.#{v.$css-prefix}-beat {
+  animation-name: #{v.$css-prefix}-beat;
+  animation-delay: var(--#{v.$css-prefix}-animation-delay, 0s);
+  animation-direction: var(--#{v.$css-prefix}-animation-direction, normal);
+  animation-duration: var(--#{v.$css-prefix}-animation-duration, 1s);
   animation-iteration-count: var(
-    --#{$fa-css-prefix}-animation-iteration-count,
+    --#{v.$css-prefix}-animation-iteration-count,
     infinite
   );
   animation-timing-function: var(
-    --#{$fa-css-prefix}-animation-timing,
+    --#{v.$css-prefix}-animation-timing,
     ease-in-out
   );
 }
 
-.#{$fa-css-prefix}-bounce {
-  animation-name: #{$fa-css-prefix}-bounce;
-  animation-delay: var(--#{$fa-css-prefix}-animation-delay, 0s);
-  animation-direction: var(--#{$fa-css-prefix}-animation-direction, normal);
-  animation-duration: var(--#{$fa-css-prefix}-animation-duration, 1s);
+.#{v.$css-prefix}-bounce {
+  animation-name: #{v.$css-prefix}-bounce;
+  animation-delay: var(--#{v.$css-prefix}-animation-delay, 0s);
+  animation-direction: var(--#{v.$css-prefix}-animation-direction, normal);
+  animation-duration: var(--#{v.$css-prefix}-animation-duration, 1s);
   animation-iteration-count: var(
-    --#{$fa-css-prefix}-animation-iteration-count,
+    --#{v.$css-prefix}-animation-iteration-count,
     infinite
   );
   animation-timing-function: var(
-    --#{$fa-css-prefix}-animation-timing,
+    --#{v.$css-prefix}-animation-timing,
     cubic-bezier(0.28, 0.84, 0.42, 1)
   );
 }
 
-.#{$fa-css-prefix}-fade {
-  animation-name: #{$fa-css-prefix}-fade;
-  animation-delay: var(--#{$fa-css-prefix}-animation-delay, 0s);
-  animation-direction: var(--#{$fa-css-prefix}-animation-direction, normal);
-  animation-duration: var(--#{$fa-css-prefix}-animation-duration, 1s);
+.#{v.$css-prefix}-fade {
+  animation-name: #{v.$css-prefix}-fade;
+  animation-delay: var(--#{v.$css-prefix}-animation-delay, 0s);
+  animation-direction: var(--#{v.$css-prefix}-animation-direction, normal);
+  animation-duration: var(--#{v.$css-prefix}-animation-duration, 1s);
   animation-iteration-count: var(
-    --#{$fa-css-prefix}-animation-iteration-count,
+    --#{v.$css-prefix}-animation-iteration-count,
     infinite
   );
   animation-timing-function: var(
-    --#{$fa-css-prefix}-animation-timing,
+    --#{v.$css-prefix}-animation-timing,
     cubic-bezier(0.4, 0, 0.6, 1)
   );
 }
 
-.#{$fa-css-prefix}-beat-fade {
-  animation-name: #{$fa-css-prefix}-beat-fade;
-  animation-delay: var(--#{$fa-css-prefix}-animation-delay, 0s);
-  animation-direction: var(--#{$fa-css-prefix}-animation-direction, normal);
-  animation-duration: var(--#{$fa-css-prefix}-animation-duration, 1s);
+.#{v.$css-prefix}-beat-fade {
+  animation-name: #{v.$css-prefix}-beat-fade;
+  animation-delay: var(--#{v.$css-prefix}-animation-delay, 0s);
+  animation-direction: var(--#{v.$css-prefix}-animation-direction, normal);
+  animation-duration: var(--#{v.$css-prefix}-animation-duration, 1s);
   animation-iteration-count: var(
-    --#{$fa-css-prefix}-animation-iteration-count,
+    --#{v.$css-prefix}-animation-iteration-count,
     infinite
   );
   animation-timing-function: var(
-    --#{$fa-css-prefix}-animation-timing,
+    --#{v.$css-prefix}-animation-timing,
     cubic-bezier(0.4, 0, 0.6, 1)
   );
 }
 
-.#{$fa-css-prefix}-flip {
-  animation-name: #{$fa-css-prefix}-flip;
-  animation-delay: var(--#{$fa-css-prefix}-animation-delay, 0s);
-  animation-direction: var(--#{$fa-css-prefix}-animation-direction, normal);
-  animation-duration: var(--#{$fa-css-prefix}-animation-duration, 1s);
+.#{v.$css-prefix}-flip {
+  animation-name: #{v.$css-prefix}-flip;
+  animation-delay: var(--#{v.$css-prefix}-animation-delay, 0s);
+  animation-direction: var(--#{v.$css-prefix}-animation-direction, normal);
+  animation-duration: var(--#{v.$css-prefix}-animation-duration, 1s);
   animation-iteration-count: var(
-    --#{$fa-css-prefix}-animation-iteration-count,
+    --#{v.$css-prefix}-animation-iteration-count,
     infinite
   );
   animation-timing-function: var(
-    --#{$fa-css-prefix}-animation-timing,
+    --#{v.$css-prefix}-animation-timing,
     ease-in-out
   );
 }
 
-.#{$fa-css-prefix}-shake {
-  animation-name: #{$fa-css-prefix}-shake;
-  animation-delay: var(--#{$fa-css-prefix}-animation-delay, 0s);
-  animation-direction: var(--#{$fa-css-prefix}-animation-direction, normal);
-  animation-duration: var(--#{$fa-css-prefix}-animation-duration, 1s);
+.#{v.$css-prefix}-shake {
+  animation-name: #{v.$css-prefix}-shake;
+  animation-delay: var(--#{v.$css-prefix}-animation-delay, 0s);
+  animation-direction: var(--#{v.$css-prefix}-animation-direction, normal);
+  animation-duration: var(--#{v.$css-prefix}-animation-duration, 1s);
   animation-iteration-count: var(
-    --#{$fa-css-prefix}-animation-iteration-count,
+    --#{v.$css-prefix}-animation-iteration-count,
     infinite
   );
-  animation-timing-function: var(--#{$fa-css-prefix}-animation-timing, linear);
+  animation-timing-function: var(--#{v.$css-prefix}-animation-timing, linear);
 }
 
-.#{$fa-css-prefix}-spin {
-  animation-name: #{$fa-css-prefix}-spin;
-  animation-delay: var(--#{$fa-css-prefix}-animation-delay, 0s);
-  animation-direction: var(--#{$fa-css-prefix}-animation-direction, normal);
-  animation-duration: var(--#{$fa-css-prefix}-animation-duration, 2s);
+.#{v.$css-prefix}-spin {
+  animation-name: #{v.$css-prefix}-spin;
+  animation-delay: var(--#{v.$css-prefix}-animation-delay, 0s);
+  animation-direction: var(--#{v.$css-prefix}-animation-direction, normal);
+  animation-duration: var(--#{v.$css-prefix}-animation-duration, 2s);
   animation-iteration-count: var(
-    --#{$fa-css-prefix}-animation-iteration-count,
+    --#{v.$css-prefix}-animation-iteration-count,
     infinite
   );
-  animation-timing-function: var(--#{$fa-css-prefix}-animation-timing, linear);
+  animation-timing-function: var(--#{v.$css-prefix}-animation-timing, linear);
 }
 
-.#{$fa-css-prefix}-spin-reverse {
-  --#{$fa-css-prefix}-animation-direction: reverse;
+.#{v.$css-prefix}-spin-reverse {
+  --#{v.$css-prefix}-animation-direction: reverse;
 }
 
-.#{$fa-css-prefix}-pulse,
-.#{$fa-css-prefix}-spin-pulse {
-  animation-name: #{$fa-css-prefix}-spin;
-  animation-direction: var(--#{$fa-css-prefix}-animation-direction, normal);
-  animation-duration: var(--#{$fa-css-prefix}-animation-duration, 1s);
+.#{v.$css-prefix}-pulse,
+.#{v.$css-prefix}-spin-pulse {
+  animation-name: #{v.$css-prefix}-spin;
+  animation-direction: var(--#{v.$css-prefix}-animation-direction, normal);
+  animation-duration: var(--#{v.$css-prefix}-animation-duration, 1s);
   animation-iteration-count: var(
-    --#{$fa-css-prefix}-animation-iteration-count,
+    --#{v.$css-prefix}-animation-iteration-count,
     infinite
   );
-  animation-timing-function: var(
-    --#{$fa-css-prefix}-animation-timing,
-    steps(8)
-  );
+  animation-timing-function: var(--#{v.$css-prefix}-animation-timing, steps(8));
 }
 
 // if agent or operating system prefers reduced motion, disable animations
 // see: https://www.smashingmagazine.com/2020/09/design-reduced-motion-sensitivities/
 // see: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
 @media (prefers-reduced-motion: reduce) {
-  .#{$fa-css-prefix}-beat,
-  .#{$fa-css-prefix}-bounce,
-  .#{$fa-css-prefix}-fade,
-  .#{$fa-css-prefix}-beat-fade,
-  .#{$fa-css-prefix}-flip,
-  .#{$fa-css-prefix}-pulse,
-  .#{$fa-css-prefix}-shake,
-  .#{$fa-css-prefix}-spin,
-  .#{$fa-css-prefix}-spin-pulse {
-    animation-delay: -1ms;
-    animation-duration: 1ms;
-    animation-iteration-count: 1;
-    transition-delay: 0s;
-    transition-duration: 0s;
+  .#{v.$css-prefix}-beat,
+  .#{v.$css-prefix}-bounce,
+  .#{v.$css-prefix}-fade,
+  .#{v.$css-prefix}-beat-fade,
+  .#{v.$css-prefix}-flip,
+  .#{v.$css-prefix}-pulse,
+  .#{v.$css-prefix}-shake,
+  .#{v.$css-prefix}-spin,
+  .#{v.$css-prefix}-spin-pulse {
+    animation: none !important;
+    transition: none !important;
   }
 }
 
-@keyframes #{$fa-css-prefix}-beat {
+@keyframes #{v.$css-prefix}-beat {
   0%,
   90% {
     transform: scale(1);
   }
   45% {
-    transform: scale(var(--#{$fa-css-prefix}-beat-scale, 1.25));
+    transform: scale(var(--#{v.$css-prefix}-beat-scale, 1.25));
   }
 }
 
-@keyframes #{$fa-css-prefix}-bounce {
+@keyframes #{v.$css-prefix}-bounce {
   0% {
     transform: scale(1, 1) translateY(0);
   }
   10% {
     transform: scale(
-        var(--#{$fa-css-prefix}-bounce-start-scale-x, 1.1),
-        var(--#{$fa-css-prefix}-bounce-start-scale-y, 0.9)
+        var(--#{v.$css-prefix}-bounce-start-scale-x, 1.1),
+        var(--#{v.$css-prefix}-bounce-start-scale-y, 0.9)
       )
       translateY(0);
   }
   30% {
     transform: scale(
-        var(--#{$fa-css-prefix}-bounce-jump-scale-x, 0.9),
-        var(--#{$fa-css-prefix}-bounce-jump-scale-y, 1.1)
+        var(--#{v.$css-prefix}-bounce-jump-scale-x, 0.9),
+        var(--#{v.$css-prefix}-bounce-jump-scale-y, 1.1)
       )
-      translateY(var(--#{$fa-css-prefix}-bounce-height, -0.5em));
+      translateY(var(--#{v.$css-prefix}-bounce-height, -0.5em));
   }
   50% {
     transform: scale(
-        var(--#{$fa-css-prefix}-bounce-land-scale-x, 1.05),
-        var(--#{$fa-css-prefix}-bounce-land-scale-y, 0.95)
+        var(--#{v.$css-prefix}-bounce-land-scale-x, 1.05),
+        var(--#{v.$css-prefix}-bounce-land-scale-y, 0.95)
       )
       translateY(0);
   }
   57% {
     transform: scale(1, 1)
-      translateY(var(--#{$fa-css-prefix}-bounce-rebound, -0.125em));
+      translateY(var(--#{v.$css-prefix}-bounce-rebound, -0.125em));
   }
   64% {
     transform: scale(1, 1) translateY(0);
@@ -187,36 +182,36 @@
   }
 }
 
-@keyframes #{$fa-css-prefix}-fade {
+@keyframes #{v.$css-prefix}-fade {
   50% {
-    opacity: var(--#{$fa-css-prefix}-fade-opacity, 0.4);
+    opacity: var(--#{v.$css-prefix}-fade-opacity, 0.4);
   }
 }
 
-@keyframes #{$fa-css-prefix}-beat-fade {
+@keyframes #{v.$css-prefix}-beat-fade {
   0%,
   100% {
-    opacity: var(--#{$fa-css-prefix}-beat-fade-opacity, 0.4);
+    opacity: var(--#{v.$css-prefix}-beat-fade-opacity, 0.4);
     transform: scale(1);
   }
   50% {
     opacity: 1;
-    transform: scale(var(--#{$fa-css-prefix}-beat-fade-scale, 1.125));
+    transform: scale(var(--#{v.$css-prefix}-beat-fade-scale, 1.125));
   }
 }
 
-@keyframes #{$fa-css-prefix}-flip {
+@keyframes #{v.$css-prefix}-flip {
   50% {
     transform: rotate3d(
-      var(--#{$fa-css-prefix}-flip-x, 0),
-      var(--#{$fa-css-prefix}-flip-y, 1),
-      var(--#{$fa-css-prefix}-flip-z, 0),
-      var(--#{$fa-css-prefix}-flip-angle, -180deg)
+      var(--#{v.$css-prefix}-flip-x, 0),
+      var(--#{v.$css-prefix}-flip-y, 1),
+      var(--#{v.$css-prefix}-flip-z, 0),
+      var(--#{v.$css-prefix}-flip-angle, -180deg)
     );
   }
 }
 
-@keyframes #{$fa-css-prefix}-shake {
+@keyframes #{v.$css-prefix}-shake {
   0% {
     transform: rotate(-15deg);
   }
@@ -249,7 +244,7 @@
   }
 }
 
-@keyframes #{$fa-css-prefix}-spin {
+@keyframes #{v.$css-prefix}-spin {
   0% {
     transform: rotate(0deg);
   }

package/nationalarchives/lib/font-awesome/_bordered.scss

@@ -0,0 +1,27 @@
+//  bordered icons
+// -------------------------
+@use "variables" as v;
+
+/* Heads Up: Bordered Icons will not be supported in the future!
+  - This feature will be deprecated in the next major release of Font Awesome (v8)!
+  - You may continue to use it in this version *v7), but it will not be supported in Font Awesome v8.
+*/
+
+/* Notes:
+* --@{v.$css-prefix}-border-width = 1/16 by default (to render as ~1px based on a 16px default font-size)
+* --@{v.$css-prefix}-border-padding =
+  ** 3/16 for vertical padding (to give ~2px of vertical whitespace around an icon considering it's vertical alignment)
+  ** 4/16 for horizontal padding (to give ~4px of horizontal whitespace around an icon)
+*/
+
+.#{v.$css-prefix}-border {
+  border-color: var(--#{v.$css-prefix}-border-color, #{v.$border-color});
+  border-radius: var(--#{v.$css-prefix}-border-radius, #{v.$border-radius});
+  border-style: var(--#{v.$css-prefix}-border-style, #{v.$border-style});
+  border-width: var(--#{v.$css-prefix}-border-width, #{v.$border-width});
+  box-sizing: var(
+    --#{v.$css-prefix}-border-box-sizing,
+    #{v.$border-box-sizing}
+  );
+  padding: var(--#{v.$css-prefix}-border-padding, #{v.$border-padding});
+}