@undrr/undrr-mangrove 1.4.0 → 1.5.0

package/scss/Components/Hero/hero.scss

@@ -27,18 +27,28 @@
   }
 
   // Button overrides
+  a.mg-button,
+  a.mg-button:hover,
+  a.mg-button:visited {
+    color: $mg-color-hero;
+  }
+
   a.mg-button-primary {
     background-color: $mg-color-neutral-0;
   }
 
-  a.mg-button-secondary {
-    background-color: rgba($mg-color-neutral-0, 0.9);
+  a.mg-button-secondary,
+  a.mg-button-secondary:hover,
+  a.mg-button-secondary:visited {
+    background-color: $mg-color-hero-button-secondary-background;
+    color: $mg-color-hero-button-secondary-color;
+    border-color: $mg-border-color-hero-button-secondary;
   }
 
-  a.mg-button,
-  a.mg-button:hover,
-  a.mg-button:visited {
-    color: $mg-color-hero;
+  a.mg-button:focus-visible {
+    box-shadow: 0 0 0 2px $mg-color-neutral-0;
+    outline: 2px solid $mg-color-neutral-0;
+    outline-offset: 2px;
   }
 
   &__overlay {
@@ -182,6 +192,15 @@ $variant-colours: (
     a.mg-button:visited {
       color: #{$color};
     }
+
+    // Preserve secondary button's dedicated tokens over the generic color above
+    a.mg-button-secondary,
+    a.mg-button-secondary:hover,
+    a.mg-button-secondary:visited {
+      background-color: $mg-color-hero-button-secondary-background;
+      color: $mg-color-hero-button-secondary-color;
+      border-color: $mg-border-color-hero-button-secondary;
+    }
   }
 }
 

package/scss/Components/MegaMenu/mega-menu.scss

@@ -2,14 +2,14 @@
   position: relative;
   background: $mg-color-white;
   box-shadow: 0 2px 3px 0 rgb(51 51 51 / 0.31);
-  z-index: 10;
+  z-index: $mg-z-index-nav;
 }
 
 .mg-mega-topbar {
   width: 100%;
   display: flex;
   align-items: flex-start;
-  z-index: 10;
+  z-index: $mg-z-index-nav;
   padding: 0;
   max-width: $mg-breakpoint-desktop;
   margin: 0 auto;
@@ -89,10 +89,10 @@
     margin: 0;
     list-style: none;
 
-    // Hide items on mobile (same as default topbar behavior)
+    // Clip overflow on mobile so the scrolling content hint works correctly.
+    // pointer-events is left as auto here — it is restricted only when JS has
+    // initialised the full mega menu (see .mg-mega-wrapper--js-active below).
     @media screen and (max-width: $mg-breakpoint-tablet) {
-      // Items are there but non-interactive on mobile (hamburger opens sidebar)
-      pointer-events: none;
       overflow: hidden;
       flex: 1;
       min-width: 0;
@@ -101,11 +101,8 @@
 
   // Hide desktop menu items on mobile/tablet, show on desktop
   &__item {
-    pointer-events: none; // on mobile we only advertise the buttons, but not clickable
-
     @media screen and (min-width: $mg-breakpoint-tablet) {
       display: block;
-      pointer-events: unset;
     }
 
     .mg-mega-content {
@@ -197,7 +194,7 @@
   border-radius: $mg-radius-tab;
   box-shadow: -1px 5px 10px -1px rgb(0 0 0 / 0.25);
   inset-inline-start: 0;
-  z-index: 1;
+  z-index: 1; // submenu floats above page content within mega-menu stacking context
   width: 100%;
 
   // Desktop: Float over content with horizontal layout
@@ -593,7 +590,7 @@
   position: absolute;
   overflow: auto;
   background-color: $mg-color-interactive-active;
-  z-index: 10;
+  z-index: $mg-z-index-nav;
 
   // Mobile-first: Full-width mobile sidebar
   width: 100%;
@@ -664,7 +661,7 @@
   cursor: pointer;
   align-items: start;
   justify-content: start;
-  z-index: 14;
+  z-index: $mg-z-index-nav-toggle;
   display: flex;
 
   // Hide mobile button on desktop
@@ -695,7 +692,7 @@
   position: absolute;
   top: 0;
   inset-inline-start: 0; // RTL-friendly
-  z-index: 9;
+  z-index: $mg-z-index-nav - 1;
   display: block;
   overflow: auto;
   background-color: $mg-color-interactive;
@@ -725,7 +722,7 @@
   border: none;
   padding: 0;
   cursor: pointer;
-  z-index: 9; // just below sidebar which has 10
+  z-index: $mg-z-index-nav - 1;
 
   // Desktop: Hide
   @media screen and (min-width: $mg-breakpoint-tablet) {
@@ -748,3 +745,19 @@
     font-family: $mg-font-family-arabic-body;
   }
 }
+
+// Full JS mega menu — sidebar handles mobile nav, so topbar items must NOT be
+// interactive on small screens. This class is added by the React component on
+// mount (useEffect), so it is absent when JS fails or has not yet hydrated,
+// preserving a clickable fallback for server-rendered nav markup.
+.mg-mega-wrapper--js-active {
+  @media screen and (max-width: $mg-breakpoint-tablet) {
+    .mg-mega-topbar__nav {
+      pointer-events: none;
+    }
+
+    .mg-mega-topbar__item {
+      pointer-events: none;
+    }
+  }
+}

package/scss/Components/OnThisPageNav/on-this-page-nav.scss

@@ -0,0 +1,206 @@
+// On this page nav
+// https://gitlab.com/undrr/web-backlog/-/issues/337
+// A sticky horizontal navigation bar that links to page sections.
+// Supports auto-detected headings or explicit author-provided links,
+// with optional CTA button and scroll-spy active state.
+
+.mg-on-this-page-nav {
+  // --mg-on-this-page-nav-offset: docking offset for fixed headers (default: 0px).
+  // Set this in your theme CSS to dock below a sticky MegaMenu or header.
+  position: sticky;
+  top: var(--mg-on-this-page-nav-offset, 0);
+  z-index: $mg-z-index-sticky; // above MegaMenu, below PageHeader
+  display: flex;
+  align-items: center;
+  background: $mg-color-neutral-0;
+  box-shadow: 0 2px 3px 0 rgb(51 51 51 / 0.31);
+  padding: 0 $mg-container-spacer;
+
+  // Full-bleed: break out of any parent container to span the viewport.
+  // Works even when nested inside an mg-container or Drupal content column.
+  width: 100vw;
+  margin-inline-start: calc(50% - 50vw);
+
+  // Un-stick on short viewports so the bar doesn't dominate the screen.
+  // GOV.UK accessibility research found sticky elements at 400% zoom consumed
+  // 30%+ of viewport — this prevents that. (technology.blog.gov.uk/2018/05/21)
+  @media screen and (height <= 400px) {
+    position: static;
+    box-shadow: none;
+    border-bottom: 1px solid $mg-color-neutral-50;
+  }
+
+  @media screen and (min-width: $mg-breakpoint-tablet) {
+    padding: 0 $mg-spacing-200;
+  }
+
+  &--hidden {
+    display: none;
+  }
+
+  &__list {
+    display: flex;
+    align-items: center;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    overflow-x: auto;
+    overscroll-behavior-x: contain;
+    flex: 1 1 auto;
+
+    // Fade gradient on the trailing edge signals more content is scrollable.
+    // Uses mask-image so the fade is transparent (works on any background).
+    // padding-inline-end gives the fade space so text isn't masked mid-character.
+    padding-inline-end: $mg-spacing-300;
+    -webkit-mask-image: linear-gradient(to right, #000 calc(100% - #{$mg-spacing-500}), transparent);
+    mask-image: linear-gradient(to right, #000 calc(100% - #{$mg-spacing-500}), transparent);
+
+    // Hide scrollbar but keep functional
+    scrollbar-width: none;
+
+    &::-webkit-scrollbar {
+      display: none;
+    }
+
+    // When content is scrolled left, also fade the leading edge so users know
+    // items are hidden behind the scroll button on that side.
+    .mg-on-this-page-nav--has-left-overflow & {
+      padding-inline-start: $mg-spacing-300;
+      -webkit-mask-image: linear-gradient(to right, transparent, #000 #{$mg-spacing-500}, #000 calc(100% - #{$mg-spacing-500}), transparent);
+      mask-image: linear-gradient(to right, transparent, #000 #{$mg-spacing-500}, #000 calc(100% - #{$mg-spacing-500}), transparent);
+    }
+  }
+
+  &__item {
+    flex-shrink: 0;
+    display: flex;
+  }
+
+  &__link {
+    display: block;
+    padding: $mg-spacing-150 $mg-spacing-150;
+    font-family: $mg-font-family-condensed;
+    font-size: $mg-font-size-250;
+    font-weight: 600;
+    color: $mg-color-neutral-600;
+    text-decoration: none;
+    white-space: nowrap;
+    border-bottom: 3px solid transparent;
+    transition: color 0.2s ease, border-color 0.2s ease;
+
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+
+    &:hover {
+      color: $mg-color-interactive-active;
+      border-bottom-color: $mg-color-interactive-active;
+      text-decoration: none;
+    }
+
+    &:focus-visible {
+      outline: 2px solid $mg-color-interactive;
+      outline-offset: -2px;
+    }
+
+    // Active state and active+hover — active wins over hover
+    &--active,
+    &--active:hover {
+      color: $mg-color-interactive;
+      border-bottom-color: $mg-color-interactive;
+    }
+  }
+
+  &__cta {
+    flex-shrink: 0;
+    margin-inline-start: auto;
+    padding: $mg-spacing-150 $mg-spacing-150;
+    font-family: $mg-font-family-condensed;
+    font-size: $mg-font-size-250;
+    font-weight: 600;
+    color: $mg-color-neutral-0;
+    background: $mg-color-interactive;
+    text-decoration: none;
+    white-space: nowrap;
+    border: 0;
+    cursor: pointer;
+    transition: background-color 0.2s ease;
+
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+
+    &:hover {
+      background: $mg-color-interactive-active;
+      text-decoration: none;
+      color: $mg-color-neutral-0;
+    }
+
+    &:focus-visible {
+      outline: 2px solid $mg-color-interactive;
+      outline-offset: 2px;
+    }
+  }
+
+  // Scroll arrow buttons — injected by JS when the list overflows.
+  // hidden attribute is toggled by JS based on scroll position.
+  &__scroll-btn {
+    flex-shrink: 0;
+    align-self: stretch;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-width: $mg-spacing-250; // WCAG 2.5.8 minimum touch target (24px)
+    padding: 0 $mg-spacing-150;
+    border: 0;
+    background: $mg-color-neutral-0;
+    cursor: pointer;
+    color: $mg-color-neutral-600;
+    transition: color 0.2s ease;
+
+    // display:flex above would otherwise override the UA [hidden]{display:none} rule
+    // since author styles always beat the user-agent stylesheet.
+    &[hidden] {
+      display: none;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+
+    &:hover {
+      color: $mg-color-interactive-active;
+    }
+
+    &:focus-visible {
+      outline: 2px solid $mg-color-interactive;
+      outline-offset: -2px;
+    }
+
+    svg {
+      display: block;
+      pointer-events: none;
+    }
+
+    // In RTL, flex reversal places prevBtn on the right and nextBtn on the left,
+    // so the chevron icons point in the opposite physical direction from the scroll.
+    // Flip them so each icon still points toward its scroll destination.
+    [dir="rtl"] & {
+      svg { transform: scaleX(-1); }
+    }
+  }
+}
+
+// RTL: flex layout places prevBtn at the right (visual-start) edge and nextBtn
+// at the left (visual-end) edge. The JS scrollBy direction, button visibility,
+// and chevron icon direction are all RTL-aware. The mask-image gradient uses
+// physical `to right` which fades the correct edge in LTR; RTL gradient
+// correction is a known open item.
+
+// Arabic font override
+:lang(ar) {
+  .mg-on-this-page-nav__link,
+  .mg-on-this-page-nav__cta {
+    font-family: $mg-font-family-arabic-headings;
+  }
+}

package/scss/Components/PageHeader/page-header.scss

@@ -12,7 +12,7 @@
       url(//www.undrr.org/themes/custom/undrr_common/images/toolbar-background.png)
       no-repeat center center;
     box-shadow: 0 2px 4px 0 rgb(0 0 0 / 0.3);
-    z-index: 22;
+    z-index: $mg-z-index-header;
 
     @media (width >= $mg-breakpoint-tablet) {
       .mg-page-header__container {

package/scss/Components/ScrollContainer/scroll-container.scss

@@ -24,7 +24,7 @@
     right: 0;
     display: flex;
     gap: $mg-spacing-50;
-    z-index: 1;
+    z-index: 1; // scroll nav above container content — local to scroll-container stacking context
 
     &-button {
       width: $mg-spacing-300;

package/scss/Components/Snackbar/snackbar.scss

@@ -8,7 +8,7 @@
   justify-content: center;
   transform: translate(-50%, -300%);
   transition: transform 0.3s ease-in-out;
-  z-index: 9999; // Ensure snackbar appears above other elements
+  z-index: $mg-z-index-toast; // above modals and all page chrome
   width: calc(100% - 32px); // Ensure it works on small screens
   max-width: 600px; // Limit width on large screens
 

package/scss/Components/SyndicationSearchWidget/syndication-search-widget.scss

@@ -999,7 +999,7 @@ $search-input-padding-x: $mg-spacing-250;
 .mg-select__backdrop {
   position: fixed;
   inset: 0;
-  z-index: 9998; // High z-index since it's portaled to body
+  z-index: $mg-z-index-modal - 1; // portaled select backdrop — uses modal layer to clear all page chrome
   background: transparent;
   cursor: default;
 }
@@ -1009,7 +1009,7 @@ $search-input-padding-x: $mg-spacing-250;
   top: 100%;
   left: 0;
   right: 0;
-  z-index: 9999; // Above backdrop
+  z-index: $mg-z-index-modal; // portaled select dropdown — uses modal layer to clear all page chrome
   background: #fff;
   border: 1px solid $search-primary;
   border-top: none;
@@ -1227,7 +1227,7 @@ $search-input-padding-x: $mg-spacing-250;
   position: fixed;
   inset: 0;
   background: rgb(0 0 0 / 0.5);
-  z-index: 1000;
+  z-index: $mg-z-index-drawer - 1; // backdrop behind drawer panel
   animation: mg-search-fade-in 0.2s ease-out;
   cursor: pointer; // Indicate clickable to close
 }
@@ -1252,7 +1252,7 @@ $search-input-padding-x: $mg-spacing-250;
   display: flex;
   flex-direction: column;
   animation: mg-search-slide-in-left 0.3s ease-out;
-  z-index: 1001;
+  z-index: $mg-z-index-drawer;
   cursor: default; // Reset cursor inside drawer
 }
 

package/scss/Components/Tab/tab.scss

@@ -18,7 +18,7 @@
       top: -$mg-spacing-25;
       margin-bottom: -$mg-spacing-25;
       position: relative;
-      z-index: 1;
+      z-index: 1; // border indicator floats above the tab list background — local to tabbar
       border-bottom: $mg-spacing-25 solid $mg-color-tab-border;
     }
   }
@@ -167,7 +167,7 @@
   background: $mg-color-tab-background--hover;
   border-bottom: $mg-spacing-25 solid $mg-color-tab-border--hover;
   color: $mg-color-text-tab--hover;
-  z-index: 1150;
+  z-index: 2; // border-overlap micro-fix within tabbar stacking context
   text-decoration: none;
 }
 

package/scss/Components/TableOfContents/TableOfContents.scss

@@ -0,0 +1,3 @@
+// TableOfContents.scss — DEPRECATED, use table-of-contents.scss
+@import "./table-of-contents";
+@warn "TableOfContents.scss is deprecated. Import table-of-contents.scss instead.";

package/scss/Components/TextCta/text-cta.scss

@@ -111,18 +111,28 @@
   }
 
   // Button overrides for dark backgrounds (matches Hero pattern)
+  a.mg-button,
+  a.mg-button:hover,
+  a.mg-button:visited {
+    color: $mg-color-hero;
+  }
+
   a.mg-button-primary {
     background-color: $mg-color-neutral-0;
   }
 
-  a.mg-button-secondary {
-    background-color: rgba($mg-color-neutral-0, 0.9);
+  a.mg-button-secondary,
+  a.mg-button-secondary:hover,
+  a.mg-button-secondary:visited {
+    background-color: $mg-color-hero-button-secondary-background;
+    color: $mg-color-hero-button-secondary-color;
+    border-color: $mg-border-color-hero-button-secondary;
   }
 
-  a.mg-button,
-  a.mg-button:hover,
-  a.mg-button:visited {
-    color: $mg-color-hero;
+  a.mg-button:focus-visible {
+    box-shadow: 0 0 0 2px $mg-color-neutral-0;
+    outline: 2px solid $mg-color-neutral-0;
+    outline-offset: 2px;
   }
 }
 

package/scss/Utilities/FullWidth/full-width.scss

@@ -15,7 +15,7 @@
   position: absolute;
   top: 0;
   width: 100vw;
-  z-index: -1;
+  z-index: $mg-z-index-behind; // pseudo-element background sits behind sibling content
 }
 
 [dir="rtl"] .mg-container-full-width::before {

package/scss/Utilities/ShowMore/show-more.scss

@@ -21,6 +21,6 @@
 
 .mg-show-more--button {
   position: relative;
-  z-index: 2;
+  z-index: 2; // button sits above the gradient fade-out overlay — local to show-more context
   padding: mg-rem(10) mg-rem(40);
 }

package/scss/assets/scss/_components.scss

@@ -12,6 +12,9 @@
 @import "../../Atom/BaseTypography/Quotation/quotation";
 @import "../../Atom/BaseTypography/Small/small";
 @import "../../Atom/Colors/color";
+
+// Icon definitions — included here so every theme CSS file contains icons.
+// See: https://github.com/unisdr/undrr-mangrove/issues/906
 @import "../../Atom/Icons/icons";
 @import "../../Atom/Images/AuthorImage/author-image";
 @import "../../Atom/Images/Image/image";
@@ -62,6 +65,7 @@
 
 // CSS+vanilla-JS component — Drupal integration via Gutenberg block, not a React export.
 @import "../../Components/TableOfContents/table-of-contents";
+@import "../../Components/OnThisPageNav/on-this-page-nav";
 @import "../../Components/SyndicationSearchWidget/syndication-search-widget";
 
 // CSS+static-HTML component — not a React export. Static pages in dist/assets/error-pages/.

package/scss/assets/scss/_variables-delta.scss

@@ -52,10 +52,12 @@ $mg-color-button: $delta-color-primary;
 $mg-color-button--hover: $delta-color-primary-800;
 $mg-color-button-background: transparent;
 $mg-color-button-background--hover: rgba($delta-color-primary, 0.06);
+$mg-color-button-secondary-background: transparent;
+$mg-color-button-secondary-background--hover: rgba($delta-color-primary, 0.06);
 $mg-color-text-button: $delta-color-primary;
 $mg-border-color-button: $delta-color-primary;
 $mg-radius-button: $mg-spacing-50;
-$mg-border-width-button: 2px;
+$mg-border-width-button: 1px;
 $mg-padding-button: $mg-spacing-100 $mg-spacing-200;
 $mg-font-size-button: $mg-font-size-250;
 
@@ -82,6 +84,9 @@ $mg-hero-overlay-max-width: $mg-width-600;
 $mg-hero-overlay-padding: $mg-spacing-400;
 $mg-color-hero-title: oklch(68.5% 0.169 237.323);
 $mg-color-hero--tertiary: $delta-color-dark; // Dark CTA banner sections
+$mg-color-hero-button-secondary-background: $delta-color-primary;
+$mg-color-hero-button-secondary-color: $mg-color-white;
+$mg-border-color-hero-button-secondary: $mg-color-white;
 $mg-spacing-hero-overlay: mg-rem(20) 0;
 
 // Tabs — TODO: underline vs boxed style needs confirmation from Delta design team

package/scss/assets/scss/_variables.scss

@@ -310,6 +310,8 @@ $mg-color-button: $mg-color-white !default;
 $mg-color-button--hover: $mg-color-white !default;
 $mg-color-button-background: $mg-color-interactive !default;
 $mg-color-button-background--hover: $mg-color-interactive-active !default;
+$mg-color-button-secondary-background: $mg-color-blue-800 !default;
+$mg-color-button-secondary-background--hover: $mg-color-blue-700 !default;
 $mg-radius-button: $mg-spacing-0 !default;
 $mg-border-width-button: 1px !default;
 $mg-color-text-button: $mg-color-white !default;
@@ -328,9 +330,9 @@ $mg-radius-form-input: $mg-spacing-0 !default;
 
 // card
 $mg-card-background: none !default;
-$mg-card-padding: 0 !default;
+$mg-card-padding: 0rem !default;
 $mg-card-border-radius: 0 !default;
-$mg-card-icon-badge-radius: 50% !default;
+$mg-card-icon-badge-radius: 20% !default;
 
 // CTA banner
 $mg-cta-padding: $mg-spacing-400 0 !default;
@@ -350,6 +352,9 @@ $mg-color-hero-title: $mg-color-neutral-0 !default;
 $mg-spacing-hero-overlay: 0 !default;
 $mg-hero-overlay-max-width: $mg-width-400 !default;
 $mg-hero-overlay-padding: $mg-spacing-200 !default;
+$mg-color-hero-button-secondary-background: rgba($mg-color-neutral-0, 0.9) !default;
+$mg-color-hero-button-secondary-color: $mg-color-hero !default;
+$mg-border-color-hero-button-secondary: $mg-color-neutral-0 !default;
 
 // mega menu
 $mg-color-mega-content-bg: $mg-color-button !default;
@@ -381,6 +386,34 @@ $mg-tabs-border-bottom: true !default;
 
 $author-image-radius: 50%;
 
+// Z-index layers: use these named tokens for global stacking contexts
+// (fixed, sticky, or portaled elements). One token per UI concept — backdrops
+// and sub-layers use $token - 1 / $token + 1 arithmetic within the component
+// SCSS rather than separate variables. Local stacking within a component's own
+// isolated context uses raw values with an explanatory comment.
+// Pick the nearest existing layer; open a GitHub discussion before adding one.
+
+/**
+ * @tokens Z-index layers
+ */
+
+// Background utility — pseudo-element placed behind all sibling content
+$mg-z-index-behind: -1;      // ::before backgrounds (e.g. mg-container-full-width)
+
+// Navigation zone — ⚠ FROZEN: Drupal themes depend on these exact values
+$mg-z-index-nav: 10;         // MegaMenu (mobile sidebar/overlay uses nav - 1 = 9)
+$mg-z-index-sticky: 11;      // Secondary sticky bars, e.g. OnThisPageNav
+$mg-z-index-nav-toggle: 14;  // Mobile nav hamburger toggle (above all nav layers)
+$mg-z-index-header: 22;      // PageHeader (above nav and sticky bar)
+
+// Overlay zone — floats above page content
+$mg-z-index-drawer: 2000;    // Drawer / side panel (backdrop uses drawer - 1 = 1999)
+$mg-z-index-dropdown: 2500;  // Dropdowns and inline menus (above drawers)
+
+// Modal zone — portaled to <body>, must clear all page chrome
+$mg-z-index-modal: 5000;     // Modal and dialog (backdrop uses modal - 1 = 4999)
+$mg-z-index-toast: 5500;     // Toast notifications (Snackbar), above modals
+
 /**
   * @tokens-end
   */