@undrr/undrr-mangrove 2.1.0 → 2.2.0

package/js/preview-access.js

@@ -4,7 +4,9 @@
 // The presence of an element with [data-mg-preview-access] in the body
 // activates the gate. CSS hides the page on parse via :has(); this script
 // layers a modal over it and asks for a PIN. On success, the gate is marked
-// unlocked and the unlock is persisted in sessionStorage.
+// unlocked, an `mg-preview-access:unlock` event is dispatched on it, and the
+// unlock is persisted in sessionStorage (default) or, with
+// data-mg-preview-persist="local", in localStorage.
 //
 // Not a security mechanism. The PIN lives in the DOM. Treat this as a
 // "wet paint" sign: strong, unmissable, but trivial to bypass for anyone
@@ -26,6 +28,10 @@ const DEFAULTS = {
 };
 
 const STORAGE_PREFIX = 'mg-preview-access:';
+const SESSION_VALUE = 'unlocked';
+const UNLOCK_EVENT = 'mg-preview-access:unlock';
+const PERSIST_MODES = ['session', 'local'];
+const DAY_MS = 24 * 60 * 60 * 1000;
 const TITLE_ID = 'mg-preview-access-title';
 const BODY_ID = 'mg-preview-access-body';
 const ERROR_ID = 'mg-preview-access-error';
@@ -40,6 +46,7 @@ const SAFE_URL_SCHEMES = ['http:', 'https:', 'mailto:'];
 // drop when a gate is detached and unreferenced.
 const overlays = new WeakMap();
 const previousFocus = new WeakMap();
+const inertSiblings = new WeakMap();
 
 /**
  * Validate that a contact URL uses an allow-listed scheme. Returns the URL
@@ -56,12 +63,27 @@ function safeContactUrl(value) {
   return DEFAULTS.contactUrl;
 }
 
+/**
+ * Parse data-mg-preview-max-age (days). Returns a positive number of days, or
+ * null for "no expiry" (missing, zero, negative or non-numeric values).
+ */
+function parseMaxAge(value) {
+  if (value === null || value === '') return null;
+  const days = Number(value);
+  return Number.isFinite(days) && days > 0 ? days : null;
+}
+
 function readConfig(el) {
+  const persist = (el.getAttribute('data-mg-preview-persist') || '')
+    .trim()
+    .toLowerCase();
   return {
     id:
       el.getAttribute('data-mg-preview-id') ||
       (typeof window !== 'undefined' ? window.location.pathname : 'default'),
     pin: el.getAttribute('data-mg-preview-pin') || DEFAULTS.pin,
+    persist: PERSIST_MODES.includes(persist) ? persist : 'session',
+    maxAge: parseMaxAge(el.getAttribute('data-mg-preview-max-age')),
     eyebrow: el.getAttribute('data-mg-preview-eyebrow') || DEFAULTS.eyebrow,
     title: el.getAttribute('data-mg-preview-title') || DEFAULTS.title,
     message: el.getAttribute('data-mg-preview-message') || DEFAULTS.message,
@@ -76,26 +98,116 @@ function readConfig(el) {
   };
 }
 
-function isUnlocked(id) {
+/**
+ * Short, non-cryptographic fingerprint of the PIN (32-bit FNV-1a, hex). Stored
+ * with a local unlock so that changing the PIN relocks every browser. The PIN
+ * is already in the DOM, so this only avoids writing it to storage verbatim;
+ * it is not a security measure.
+ */
+function pinFingerprint(pin) {
+  let hash = 0x811c9dc5;
+  const str = String(pin);
+  for (let i = 0; i < str.length; i += 1) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16);
+}
+
+/**
+ * A local unlock is valid when it was made with the current PIN and, if a
+ * max age is set, is not older than that. Anything else (old format, other
+ * PIN, expired, unparseable) is treated as locked.
+ */
+function isValidLocalEntry(raw, config) {
+  let entry;
   try {
-    return sessionStorage.getItem(STORAGE_PREFIX + id) === 'unlocked';
+    entry = JSON.parse(raw);
   } catch (e) {
     return false;
   }
+  if (!entry || entry.pin !== pinFingerprint(config.pin)) return false;
+  // Require the format we write, even when expiry is not configured. A future
+  // timestamp (including after a clock correction) must not extend an unlock.
+  const at = entry.at;
+  const age = Date.now() - at;
+  if (typeof at !== 'number' || !Number.isFinite(at) || at < 0 || age < 0)
+    return false;
+  return config.maxAge === null || age < config.maxAge * DAY_MS;
 }
 
-function persistUnlock(id) {
+function hasLocalUnlock(config) {
+  const key = STORAGE_PREFIX + config.id;
   try {
-    sessionStorage.setItem(STORAGE_PREFIX + id, 'unlocked');
+    const raw = localStorage.getItem(key);
+    if (raw === null) return false;
+    if (isValidLocalEntry(raw, config)) return true;
+    // Expired or made with another PIN: drop it so it cannot linger.
+    localStorage.removeItem(key);
+  } catch (e) {
+    // Storage unavailable (private mode, blocked): treat as locked.
+  }
+  return false;
+}
+
+function hasSessionUnlock(config) {
+  try {
+    return sessionStorage.getItem(STORAGE_PREFIX + config.id) === SESSION_VALUE;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * The session flag is honoured in both modes, so a tab that is already
+ * unlocked stays unlocked when a site switches to persist="local".
+ */
+function isUnlocked(config) {
+  if (config.persist === 'local' && hasLocalUnlock(config)) return true;
+  return hasSessionUnlock(config);
+}
+
+function persistSession(id) {
+  try {
+    sessionStorage.setItem(STORAGE_PREFIX + id, SESSION_VALUE);
   } catch (e) {
     // Private mode etc. — best effort.
   }
 }
 
+function persistUnlock(config) {
+  if (config.persist === 'local') {
+    try {
+      localStorage.setItem(
+        STORAGE_PREFIX + config.id,
+        JSON.stringify({ pin: pinFingerprint(config.pin), at: Date.now() })
+      );
+      return;
+    } catch (e) {
+      // localStorage blocked or full: fall back to this tab only.
+    }
+  }
+  persistSession(config.id);
+}
+
 function markUnlocked(gate) {
   gate.classList.add('mg-preview-access--unlocked');
 }
 
+/**
+ * Tell the host page the gate is open. Bubbles, so a listener on document
+ * registered before this script runs also hears the storage-restore case.
+ * `source` is "pin" (just entered) or "storage" (restored on init).
+ */
+function dispatchUnlock(gate, config, source) {
+  gate.dispatchEvent(
+    new CustomEvent(UNLOCK_EVENT, {
+      bubbles: true,
+      detail: { id: config.id, persist: config.persist, source },
+    })
+  );
+}
+
 function escapeText(value) {
   return String(value).replace(
     /[&<>"']/g,
@@ -150,39 +262,76 @@ function buildOverlay(config) {
  * so the redundant aria-hidden writes are intentionally omitted (ARIA 1.2).
  */
 function setSiblingsInert(overlay, on) {
-  Array.from(document.body.children).forEach(child => {
-    if (child === overlay) return;
-    if (on) {
-      child.setAttribute('inert', '');
-    } else {
-      child.removeAttribute('inert');
-    }
-  });
+  if (on) {
+    const siblings = Array.from(document.body.children).filter(
+      child => child !== overlay && !child.hasAttribute('inert')
+    );
+    inertSiblings.set(overlay, siblings);
+    siblings.forEach(child => child.setAttribute('inert', ''));
+  } else {
+    // Only undo this gate's changes; authored inactive content stays inert.
+    (inertSiblings.get(overlay) || []).forEach(child =>
+      child.removeAttribute('inert')
+    );
+    inertSiblings.delete(overlay);
+  }
+}
+
+/**
+ * Focus an element that may not be focusable on its own (<main>, a heading,
+ * <body>). A temporary tabindex="-1" is added when it has none and removed on
+ * blur, so the page's tab order is left as it was.
+ */
+function focusElement(el) {
+  if (!el || !el.isConnected || typeof el.focus !== 'function') return false;
+  if (el.closest('[inert], [hidden]') || el.matches(':disabled')) return false;
+  const temporary = !el.hasAttribute('tabindex') && el.tabIndex < 0;
+  const cleanup = () => {
+    if (el.getAttribute('tabindex') === '-1') el.removeAttribute('tabindex');
+  };
+  if (temporary) el.setAttribute('tabindex', '-1');
+  el.focus({ preventScroll: true });
+  if (document.activeElement !== el) {
+    if (temporary) cleanup();
+    return false;
+  }
+  if (temporary) el.addEventListener('blur', cleanup, { once: true });
+  return true;
+}
+
+/**
+ * Try previous focus, main landmarks, the skip-link target, headings and body.
+ * Connected targets may still be hidden or disabled; only stop once focus
+ * actually moves. This also handles CMS pages with an inactive main landmark.
+ */
+function focusAfterUnlock(gate) {
+  const saved = previousFocus.get(gate);
+  const targets = [
+    saved !== document.body ? saved : null,
+    ...document.querySelectorAll('main, [role="main"]'),
+    document.getElementById('main'),
+    ...document.querySelectorAll('h1'),
+    document.body,
+  ];
+  targets.some(focusElement);
 }
 
 function unlockGate(gate, overlay, config) {
-  persistUnlock(config.id);
+  persistUnlock(config);
+  // Reveal first: the CSS gate hides content with visibility: hidden, and
+  // hidden elements cannot take focus.
   markUnlocked(gate);
   setSiblingsInert(overlay, false);
   overlay.remove();
   overlays.delete(gate);
 
-  // Return focus to a known landmark so keyboard and screen reader users are
-  // not dropped on document.body with no announcement of the state change.
-  // The previously focused element (often body itself before mount) is the
-  // safest fallback; otherwise focus the now-revealed <main> or first heading.
-  const restore =
-    previousFocus.get(gate) ||
-    document.querySelector('main, [role="main"]') ||
-    document.querySelector('h1, h2') ||
-    document.body;
+  // Move focus to the revealed content so keyboard and screen reader users
+  // are not dropped on document.body with no sign that the page changed.
+  focusAfterUnlock(gate);
   previousFocus.delete(gate);
-  if (restore && typeof restore.focus === 'function') {
-    if (restore === document.body && !restore.hasAttribute('tabindex')) {
-      restore.setAttribute('tabindex', '-1');
-    }
-    restore.focus({ preventScroll: true });
-  }
+
+  // Dispatch last, so listeners see the final state (overlay gone, focus set).
+  dispatchUnlock(gate, config, 'pin');
 }
 
 function bindHandlers(overlay, gate, config) {
@@ -232,8 +381,9 @@ export function mgPreviewAccess(scope) {
 
     const config = readConfig(gate);
 
-    if (isUnlocked(config.id)) {
+    if (isUnlocked(config)) {
       markUnlocked(gate);
+      dispatchUnlock(gate, config, 'storage');
       return;
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@undrr/undrr-mangrove",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Mangrove design System for UNDRR",
   "files": [
     "components/**/*",

package/scss/Atom/BaseTypography/Blockquote/blockquote.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/BaseTypography/BaseTypography.mdx
  */
+@use "../../../assets/scss/breakpoints" as *;
+
 .mg-body blockquote,
 .mg-content blockquote {
   font-size: var(--mg-font-size-600);

package/scss/Atom/BaseTypography/Cite/cite.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/BaseTypography/BaseTypography.mdx
  */
+@use "../../../assets/scss/config" as *;
+
 .mg-body cite,
 .mg-content cite {
   display: block;

package/scss/Atom/BaseTypography/Code/code.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/BaseTypography/BaseTypography.mdx
  */
+@use "../../../assets/scss/config" as *;
+
 .mg-code,
 code {
   background: rgb(var(--mg-color-interactive) / 0.08);

package/scss/Atom/BaseTypography/Mark/mark.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/BaseTypography/BaseTypography.mdx
  */
+@use "../../../assets/scss/breakpoints" as *;
+
 mark {
   background: var(--mg-color-yellow-light);
   font-size: var(--mg-font-size-200);

package/scss/Atom/BaseTypography/Small/small.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/BaseTypography/BaseTypography.mdx
  */
+@use "../../../assets/scss/mixins" as *;
+
 small {
   @extend %paragraph-font-100;
 }

package/scss/Atom/Icons/icons.scss

@@ -16,8 +16,9 @@
 // See: https://github.com/unisdr/undrr-mangrove/issues/906
 
 // Icon definitions (auto-generated by scripts/icon-build.cjs).
-// Must be imported before any rules to satisfy CSS @import ordering.
-@import "icon-definitions";
+// Module dependencies must precede executable rules.
+@use "icon-definitions" as *;
+@use "../../assets/scss/config" as *;
 
 // Font fallback (kept for fa-* selectors — removed in phase 4)
 

package/scss/Atom/Images/ImageCaptionCredit/image-caption-credit.scss

@@ -6,6 +6,9 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/Images/ImageCaptionCredit/ImageCaptionCredit.mdx
  */
+@use "../../../assets/scss/mixins" as *;
+@use "../../../assets/scss/breakpoints" as *;
+
 // @import '../../../assets/scss/base';
 
 /* image with caption start */

package/scss/Atom/Images/ImageCredit/image-credit.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/Images/ImageCaptionCredit/ImageCaptionCredit.mdx
  */
+@use "../../../assets/scss/breakpoints" as *;
+
 .mg-credits {
   font-size: var(--mg-font-size-200);
   line-height: 1.4;

package/scss/Atom/Layout/Container/container.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/Layout/Container/Container.mdx
  */
+@use "../../../assets/scss/config" as *;
+
 // Define your breakpoints if not already defined
 // $mg-breakpoint-mobile: 480px;
 // $mg-breakpoint-tablet: 768px;

package/scss/Atom/Layout/Grid/grid.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/Layout/Grid/Grid.mdx
  */
+@use "../../../assets/scss/config" as *;
+
 /* Our custom css grid based on https://stable.visual-framework.dev/components/vf-grid/ */
 g-grid {
   display: flex;

package/scss/Atom/Logo/logo.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/Logo/Logo.mdx
  */
+@use "../../assets/scss/config" as *;
+
 .mg-logo {
   display: block;
   max-inline-size: 100%;

package/scss/Atom/Navigation/MenuItems/menu-items.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/Typography/Links/Links.mdx
  */
+@use "../../../assets/scss/mixins" as *;
+
 // * menu item row start *//
 .menu li {
   a {

package/scss/Atom/ReachElement/Details/details.scss

@@ -6,6 +6,9 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/BaseTypography/BaseTypography.mdx
  */
+@use "../../../assets/scss/mixins" as *;
+@use "../../../assets/scss/config" as *;
+
 /* details tag start */
 
 /* Baseline: usability essentials for all <details> elements */

package/scss/Atom/ReachElement/Figcaption/figcaption.scss

@@ -6,6 +6,9 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/BaseTypography/BaseTypography.mdx
  */
+@use "../../../assets/scss/mixins" as *;
+@use "../../../assets/scss/config" as *;
+
 /* figure tag start */
 figure {
   margin: 0;

package/scss/Atom/StatusLabel/status-label.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/StatusLabel/StatusLabel.mdx
  */
+@use "../../assets/scss/mixins" as *;
+
 // Status label — a workflow status shown as a coloured indicator plus its name.
 // -
 // Sourced from the DELTA design system board "Status Labels for Records and

package/scss/Atom/Table/table.scss

@@ -6,6 +6,10 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/Table/Table.mdx
  */
+@use "../../assets/scss/breakpoints" as *;
+@use "../../assets/scss/mixins" as *;
+@use "../../assets/scss/config" as *;
+
 /* table tag start */
 .mg-table {
   border-collapse: collapse;

package/scss/Atom/Tag/tag.scss

@@ -6,6 +6,9 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Atom/Tag/Tag.mdx
  */
+@use "../../assets/scss/mixins" as *;
+@use "../../assets/scss/config" as *;
+
 // Compact taxonomy labels. Keep legacy theme overrides and container markup.
 // :where() gives auto-styled children the same specificity as .mg-tag, so
 // explicit modifiers win regardless of which markup a Drupal view emits.

package/scss/Components/Boilerplate/boilerplate.scss

@@ -6,6 +6,9 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Components/Boilerplate/Boilerplate.mdx
  */
+@use "../../assets/scss/mixins" as *;
+@use "../../assets/scss/config" as *;
+
 // Boilerplate component styles
 // We use the 'mg-' prefix for our CSS classes to namespace them
 // Sass variables are handled by the import from _components.scss

package/scss/Components/Breadcrumbs/breadcrumbs.scss

@@ -6,6 +6,8 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Components/Breadcrumbs/Breadcrumbs.mdx
  */
+@use "../../assets/scss/mixins" as *;
+
 .mg-breadcrumb {
   font-family: var(--mg-font-family-ui);
   font-weight: 400;

package/scss/Components/Buttons/Chips/chips.scss

@@ -6,6 +6,9 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Components/Buttons/Chips/Chips.mdx
  */
+@use "../../../assets/scss/mixins" as *;
+@use "../../../assets/scss/config" as *;
+
 .mg-chip {
   align-items: center;
   background: rgb(var(--mg-color-neutral-50));

package/scss/Components/Buttons/CtaButton/buttons.scss

@@ -7,5 +7,5 @@
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Components/Buttons/CtaButton/CtaButton.mdx
  */
 // buttons.scss — DEPRECATED, use cta-button.scss
-@import "./cta-button";
+@forward "./cta-button";
 @warn "buttons.scss is deprecated. Import cta-button.scss instead.";

package/scss/Components/Buttons/CtaButton/cta-button.scss

@@ -6,6 +6,10 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Components/Buttons/CtaButton/CtaButton.mdx
  */
+@use "../../../assets/scss/breakpoints" as *;
+@use "../../../assets/scss/mixins" as *;
+@use "../../../assets/scss/config" as *;
+
 // .mg-buttons {
 //   margin-bottom: 1em;
 //   //Media queries

package/scss/Components/Buttons/ShareButtons/share-buttons.scss

@@ -6,6 +6,9 @@
  * Full documentation:
  * https://github.com/PreventionWeb/undrr-mangrove/blob/main/stories/Components/Buttons/ShareButtons/ShareButtons.mdx
  */
+@use "../../../assets/scss/mixins" as *;
+@use "../../../assets/scss/config" as *;
+
 .mg-share {
   max-inline-size: mg-rem(400);
   min-inline-size: 0;