From 637bce8a327421a91e373b2f3766f99900340f4a Mon Sep 17 00:00:00 2001
From: Carl Whittaker <carl359@gmail.com>
Date: Fri, 28 Jun 2024 17:31:19 +0100
Subject: [PATCH] fix(ENG-813): stack the consent banner behind all modals

this adds a constant that ensures that the consent banner (and other
future banners) will be stacked behind all modals.

hopefully this approach will help future visitors to the file from
regressing this issue since the constants will reveal the intent.
---
 src/components/molecules/OakModal/OakModal.tsx |  3 +++
 .../OakCookieBanner/OakCookieBanner.tsx        | 18 ++++++++++++++----
 .../OakCookieConsent/OakCookieConsent.tsx      |  3 +++
 src/styles/theme/zIndex.ts                     | 13 ++++++++++---
 4 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/src/components/molecules/OakModal/OakModal.tsx b/src/components/molecules/OakModal/OakModal.tsx
index 049b2fc7..0307a7a9 100644
--- a/src/components/molecules/OakModal/OakModal.tsx
+++ b/src/components/molecules/OakModal/OakModal.tsx
@@ -47,6 +47,9 @@ export type OakModalProps = {
    *
    * Defaults to token: `modal-dialog`
    *
+   * 🚨 This prop is intended for use by consumers that do not use
+   * the internal system of z-index tokens.
+   *
    * NB *The modal is rendered inside a portal so it will not respect the stacking context of its parent component*.
    */
   zIndex?: number;
diff --git a/src/components/organisms/OakCookieBanner/OakCookieBanner.tsx b/src/components/organisms/OakCookieBanner/OakCookieBanner.tsx
index c40e8d63..cdf5783b 100644
--- a/src/components/organisms/OakCookieBanner/OakCookieBanner.tsx
+++ b/src/components/organisms/OakCookieBanner/OakCookieBanner.tsx
@@ -49,7 +49,10 @@ export type OakCookieBannerProps = {
   /**
    * Optional z-index override of the banner.
    *
-   * Defaults to token: `in-front`
+   * Defaults to token: `banner`
+   *
+   * 🚨 This prop is intended for use by consumers that do not use
+   * the internal system of z-index tokens.
    */
   zIndex?: number;
 };
@@ -67,6 +70,15 @@ export const OakCookieBanner = ({
   isFixed = false,
   zIndex,
 }: OakCookieBannerProps) => {
+  const finalZIndex = (() => {
+    if (typeof zIndex === "number") {
+      return zIndex;
+    }
+    if (isFixed) {
+      return "banner";
+    }
+  })();
+
   return (
     <OakBox
       $background="bg-neutral"
@@ -76,9 +88,7 @@ export const OakCookieBanner = ({
       $bottom={isFixed ? "all-spacing-0" : undefined}
       $right={isFixed ? "all-spacing-0" : undefined}
       $left={isFixed ? "all-spacing-0" : undefined}
-      $zIndex={
-        typeof zIndex === "number" ? zIndex : isFixed ? "in-front" : undefined
-      }
+      $zIndex={finalZIndex}
       $color="text-primary"
       data-testid="cookie-banner"
     >
diff --git a/src/components/organisms/OakCookieConsent/OakCookieConsent.tsx b/src/components/organisms/OakCookieConsent/OakCookieConsent.tsx
index b57af13b..12aebebc 100644
--- a/src/components/organisms/OakCookieConsent/OakCookieConsent.tsx
+++ b/src/components/organisms/OakCookieConsent/OakCookieConsent.tsx
@@ -14,6 +14,9 @@ export type OakCookieConsentProps = Pick<
   Pick<OakCookieBannerProps, "isFixed" | "innerMaxWidth"> & {
     /**
      * Optional stacking context for the entire consent UI
+     *
+     * 🚨 This prop is intended for use by consumers that do not use
+     * the internal system of z-index tokens.
      */
     zIndex?: number;
   };
diff --git a/src/styles/theme/zIndex.ts b/src/styles/theme/zIndex.ts
index 874d97f6..d9b9e313 100644
--- a/src/styles/theme/zIndex.ts
+++ b/src/styles/theme/zIndex.ts
@@ -1,11 +1,18 @@
+// For help with defining z-index values, refer to this article:
+// https://www.smashingmagazine.com/2021/02/css-z-index-large-projects/#a-new-solution
+const behind = -1;
+const modalDialog = 300;
+const banner = behind + modalDialog;
+
 export const oakZIndexTokens = {
-  behind: -1,
+  behind,
   neutral: 0,
   "in-front": 1,
   "mobile-filters": 2,
   "fixed-header": 100,
   "modal-close-button": 150,
-  "modal-dialog": 300,
-};
+  "modal-dialog": modalDialog,
+  banner,
+} as const;
 
 export type OakZIndexToken = keyof typeof oakZIndexTokens | null;