@undrr/undrr-mangrove 2.0.0-rc.2 → 2.0.0

package/js/hub-header.js

@@ -0,0 +1,217 @@
+// mg-hub-header
+// Enhances static HubHeader markup: marks the current section from the URL
+// (opt in), keeps the marked section in view and drives the edge fades.
+// See stories/Patterns/ContentHub/ContentHub.mdx.
+
+const ROOT_SELECTOR = '[data-mg-js-hub-header]';
+const ANCESTOR_CLASS = 'mg-hub-header__nav-item--ancestor';
+
+/**
+ * Reduces a link to a path that can be compared with the current page: same
+ * origin only, with no query, fragment, trailing slash or `index.html`.
+ *
+ * @param {string} href - Link href, relative or absolute.
+ * @param {string} [base] - Base URL. Defaults to the current location.
+ * @returns {string|null} The path, or null for another origin or a bad URL.
+ */
+export function hubHeaderPath(href, base = window.location.href) {
+  let url;
+  try {
+    url = new URL(href, base);
+  } catch {
+    return null;
+  }
+  if (url.origin !== new URL(base).origin) return null;
+  const path = url.pathname.replace(/\/index\.html?$/i, '/');
+  return path.length > 1 ? path.replace(/\/+$/, '') || '/' : path;
+}
+
+/**
+ * Whether the markup already says which section is current. A server or a
+ * React consumer that knows better than the URL always wins.
+ *
+ * @param {HTMLElement} root - The hub header.
+ * @returns {boolean} True when any section is already marked.
+ */
+function hasExplicitState(root) {
+  return Boolean(
+    root.querySelector(
+      `.mg-hub-header__nav [aria-current], .mg-hub-header__nav [data-hub-current], .${ANCESTOR_CLASS}`
+    )
+  );
+}
+
+/**
+ * The path a link points at, or null when it does not point at a page: an
+ * empty href, a fragment or a bare query resolves to the current page, so it
+ * would match wherever the markup is copied.
+ *
+ * @param {Element} link - The link.
+ * @returns {string|null} The link's path.
+ */
+function linkPath(link) {
+  const href = (link.getAttribute('href') || '').trim();
+  if (!href || href.startsWith('#') || href.startsWith('?')) return null;
+  return hubHeaderPath(href);
+}
+
+/**
+ * Marks the section for the current page. An exact match is the page itself
+ * and is announced; otherwise the longest section containing the page is
+ * marked as its ancestor, styled the same but not announced.
+ *
+ * @param {HTMLElement} root - The hub header.
+ * @returns {Function} Removes the marks this call added.
+ */
+function markCurrent(root) {
+  const none = () => {};
+  if (hasExplicitState(root)) return none;
+  const here = hubHeaderPath(window.location.href);
+  const name = root.querySelector('.mg-hub-header__name[href]');
+  const home = name ? linkPath(name) : null;
+  const links = [...root.querySelectorAll('.mg-hub-header__nav a[href]')];
+  const paths = links.map(linkPath);
+
+  const exact = links.find((link, index) => paths[index] === here);
+  if (exact) {
+    exact.setAttribute('aria-current', 'page');
+    exact.setAttribute('data-hub-current', '');
+    return () => {
+      exact.removeAttribute('aria-current');
+      exact.removeAttribute('data-hub-current');
+    };
+  }
+  if (home && home === here && !name.hasAttribute('aria-current')) {
+    name.setAttribute('aria-current', 'page');
+    return () => name.removeAttribute('aria-current');
+  }
+
+  // A section that is the hub home, or the site root, contains every page of
+  // the hub. As an ancestor it would be marked everywhere, so it can only ever
+  // match exactly.
+  let best = null;
+  links.forEach((link, index) => {
+    const path = paths[index];
+    if (!path || path === '/' || path === home) return;
+    if (!here.startsWith(`${path}/`)) return;
+    if (!best || path.length > best.path.length) best = { link, path };
+  });
+  if (!best) return none;
+  const item = best.link.closest('li');
+  item?.classList.add(ANCESTOR_CLASS);
+  best.link.setAttribute('data-hub-current', '');
+  return () => {
+    item?.classList.remove(ANCESTOR_CLASS);
+    best.link.removeAttribute('data-hub-current');
+  };
+}
+
+/**
+ * Keeps the marked section in view and drives the edge fades, which CSS
+ * cannot do on its own because it cannot detect overflow.
+ *
+ * @param {HTMLElement} root - The hub header.
+ * @returns {Function} Removes the listeners and markers this added.
+ */
+function enhanceRail(root) {
+  const nav = root.querySelector('.mg-hub-header__nav');
+  const rail = nav?.querySelector('ul');
+  if (!nav || !rail) return () => {};
+
+  const reveal = () => {
+    const selected = rail.querySelector('[data-hub-current]');
+    if (!selected || typeof rail.scrollBy !== 'function') return;
+    const viewport = rail.getBoundingClientRect();
+    const item = selected.getBoundingClientRect();
+    let offset = 0;
+    if (item.left < viewport.left) offset = item.left - viewport.left;
+    else if (item.right > viewport.right) offset = item.right - viewport.right;
+    if (offset) rail.scrollBy({ left: offset, behavior: 'instant' });
+  };
+  const markOverflow = () => {
+    const scrolled = Math.abs(rail.scrollLeft);
+    nav.toggleAttribute('data-overflow-start', scrolled > 1);
+    nav.toggleAttribute(
+      'data-overflow-end',
+      scrolled + rail.clientWidth < rail.scrollWidth - 1
+    );
+  };
+  const update = () => {
+    reveal();
+    markOverflow();
+  };
+
+  update();
+  // Only a change to the marked label, such as a web font arriving after first
+  // paint, moves the rail back to it. Everything else only recomputes the
+  // fades: a resize must not undo the reader's own scrolling, and iOS Safari
+  // fires one whenever its toolbar collapses.
+  const Observer =
+    typeof ResizeObserver === 'undefined' ? null : ResizeObserver;
+  const railObserver = Observer ? new Observer(markOverflow) : null;
+  railObserver?.observe(nav);
+  railObserver?.observe(rail);
+  const labelObserver = Observer ? new Observer(update) : null;
+  const selected = rail.querySelector('[data-hub-current]');
+  if (selected) labelObserver?.observe(selected);
+  let active = true;
+  document.fonts?.ready.then(() => {
+    if (active) update();
+  });
+  rail.addEventListener('scroll', markOverflow, { passive: true });
+  window.addEventListener('resize', markOverflow);
+
+  return () => {
+    active = false;
+    railObserver?.disconnect();
+    labelObserver?.disconnect();
+    rail.removeEventListener('scroll', markOverflow);
+    window.removeEventListener('resize', markOverflow);
+    nav.removeAttribute('data-overflow-start');
+    nav.removeAttribute('data-overflow-end');
+  };
+}
+
+/**
+ * Initializes hub headers. Headers already initialized are skipped, so this
+ * can be called again after inserting markup.
+ *
+ * @param {NodeList|HTMLElement[]|HTMLElement} [scope] - Headers to enhance.
+ *   Defaults to every [data-mg-js-hub-header] in the document, less any
+ *   carrying data-mg-hub-header-skip-auto-init.
+ * @returns {Function} Removes what this call added, so a header can be
+ *   initialized again. Useful for React effect cleanup.
+ */
+export function mgHubHeader(scope) {
+  let roots;
+  if (!scope) roots = document.querySelectorAll(ROOT_SELECTOR);
+  else if (scope instanceof HTMLElement) roots = [scope];
+  else roots = scope;
+
+  const cleanups = [];
+  Array.from(roots).forEach(root => {
+    if (!(root instanceof HTMLElement) || !root.matches(ROOT_SELECTOR)) return;
+    if (!scope && root.hasAttribute('data-mg-hub-header-skip-auto-init')) {
+      return;
+    }
+    if (root.dataset.mgJsHubHeaderInitialized === 'true') return;
+    root.dataset.mgJsHubHeaderInitialized = 'true';
+    const unmark = root.hasAttribute('data-mg-hub-header-detect-current')
+      ? markCurrent(root)
+      : () => {};
+    const teardown = enhanceRail(root);
+    cleanups.push(() => {
+      teardown();
+      unmark();
+      delete root.dataset.mgJsHubHeaderInitialized;
+    });
+  });
+  return () => cleanups.forEach(cleanup => cleanup());
+}
+
+// Auto-wrap so the browser Event object is not passed as scope.
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', () => mgHubHeader(), false);
+} else {
+  mgHubHeader();
+}

package/js/show-more.js

@@ -1,14 +1,81 @@
 // mg-show-more
 // https://gitlab.com/undrr/web-backlog/-/issues/1082
 
+// Used to give an unlabelled target an id so the toggle can point
+// `aria-controls` at it. The counter lives on `globalThis` rather than in
+// module scope so two loaded copies of this module — a site bundle alongside
+// the CDN build, say — share one sequence instead of each minting
+// `mg-show-more-target-1`. Same hazard, and same fix, as the root counter in
+// `src/hydrate.js` (#1178).
+const TARGET_COUNTER_KEY = Symbol.for('undrr.mangrove.showMore.targetCounter');
+
+/**
+ * Mints an id that is unused in the current document.
+ *
+ * @returns {string} A free `mg-show-more-target-N` id.
+ */
+function nextTargetId() {
+  for (;;) {
+    const current = globalThis[TARGET_COUNTER_KEY];
+    const next = Number.isSafeInteger(current) && current >= 0 ? current : 0;
+    globalThis[TARGET_COUNTER_KEY] = next + 1;
+    const id = `mg-show-more-target-${next}`;
+    if (!document.getElementById(id)) return id;
+  }
+}
+
+/**
+ * Resolves a toggle's target, nearest scope first.
+ *
+ * The revealed content need not be a sibling or descendant of its toggle, so
+ * there is no container the lookup can be confined to. It can still be
+ * *ordered*: climb the toggle's ancestors and return the first match found
+ * inside one. For the canonical markup that is the adjacent wrapper, and for
+ * two blocks in separate subtrees each toggle finds its own.
+ *
+ * For a toggle that is in the document the walk ends at `<html>`, an ancestor
+ * of every other element, so its last iteration *is* the document-wide lookup:
+ * a target anywhere on the page is still found, and it is the same element
+ * `document.querySelector` returned whenever nothing nearer matched. The walk
+ * is therefore never worse, and better whenever two toggles share a selector.
+ * The explicit fallback below is only reached when the toggle is not in the
+ * document tree — detached, or inside a shadow root or a `<template>` — where
+ * it resolves exactly as it did before.
+ *
+ * Two toggles under the *same* parent still cannot be told apart: the first
+ * scope containing one target contains both, and the earlier one in document
+ * order wins. That is also why the React `ShowMore` wrapper mints an id per
+ * item rather than relying on this walk. See #1228.
+ *
+ * @param {HTMLElement} toggle - The toggle whose target to resolve.
+ * @param {string} selector - The CSS selector to resolve.
+ * @returns {Element|null} The nearest match, or null when nothing matches.
+ */
+function resolveTarget(toggle, selector) {
+  for (let scope = toggle.parentElement; scope; scope = scope.parentElement) {
+    const match = scope.querySelector(selector);
+    if (match) return match;
+  }
+  // `<html>` itself, and anything outside the toggle's ancestor chain (a
+  // detached toggle, say), are only reachable from the document.
+  return document.querySelector(selector);
+}
+
 /**
  * Initializes "show more" toggle buttons.
  *
+ * The toggle carries `aria-controls` pointing at the content it collapses.
+ * It deliberately does not carry `aria-expanded`: the collapse is visual
+ * only. See the accessibility section of `ShowMore.mdx` for why.
+ *
  * @param {NodeList|HTMLElement[]|HTMLElement} [scope] - Elements to init.
  *   Accepts a NodeList, array, or a single HTMLElement.
  *   Defaults to all [data-mg-show-more] in the document.
+ * @returns {Function} Removes handlers added by this call and restores each
+ *   target's initial collapsed state. Useful for React effect cleanup.
  */
 export function mgShowMore(scope) {
+  const cleanups = [];
   const mgShowMoreButtons = scope
     ? scope instanceof HTMLElement
       ? [scope]
@@ -19,14 +86,9 @@ export function mgShowMore(scope) {
     // Skip auto-init if the element opts out
     if (!scope && item.hasAttribute('data-mg-show-more-skip-auto-init')) return;
     if (item.dataset.mgShowMoreInitialized) return;
-    item.dataset.mgShowMoreInitialized = 'true';
-
-    item.dataset.dataVfGoogleAnalyticsLabel =
-      'Show more: ' + item.dataset.mgShowMoreLabelCollapsed || `Show more`;
-
     const mgShowMoreTargetClass =
       item.dataset.mgShowMoreTarget || '.mg-show-more--container';
-    const mgShowMoreTarget = document.querySelector(mgShowMoreTargetClass);
+    const mgShowMoreTarget = resolveTarget(item, mgShowMoreTargetClass);
 
     if (!mgShowMoreTarget) {
       console.warn(
@@ -35,7 +97,42 @@ export function mgShowMore(scope) {
       return;
     }
 
-    item.addEventListener('click', event => {
+    item.dataset.mgShowMoreInitialized = 'true';
+    const wasCollapsed = mgShowMoreTarget.classList.contains(
+      'mg-show-more--collapsed'
+    );
+    const wasOpen = item.classList.contains('mg-show-more--button--open');
+    const initialText = item.textContent;
+    const initialControls = item.getAttribute('aria-controls');
+    const initialRole = item.getAttribute('role');
+    const onKeydown = event => {
+      if (event.key === ' ' || event.key === 'Spacebar') {
+        event.preventDefault();
+        item.click();
+      }
+    };
+
+    item.dataset.dataVfGoogleAnalyticsLabel =
+      'Show more: ' + (item.dataset.mgShowMoreLabelCollapsed || 'Show more');
+
+    // Relate the toggle to the content it acts on. A <button> already
+    // announces as a button; an anchor copied from an earlier version of the
+    // docs needs the role.
+    if (mgShowMoreTarget.id === '') {
+      mgShowMoreTarget.id = nextTargetId();
+    }
+    item.setAttribute('aria-controls', mgShowMoreTarget.id);
+    if (item.tagName !== 'BUTTON') {
+      item.setAttribute('role', 'button');
+
+      // `role="button"` promises Space activates the control, and an anchor
+      // does not honour that on its own (WCAG 4.1.2 Name, Role, Value).
+      // `preventDefault` keeps Space from scrolling the page.
+      item.addEventListener('keydown', onKeydown);
+    }
+
+    const onClick = event => {
+      // Also neutralises the dead `href="#"` on a legacy anchor toggle.
       event.preventDefault();
       mgShowMoreTarget.classList.toggle('mg-show-more--collapsed');
 
@@ -51,18 +148,55 @@ export function mgShowMore(scope) {
       } else {
         item.classList.add('mg-show-more--button--open');
       }
-    });
+    };
+    item.addEventListener('click', onClick);
+
+    // The collapse is `max-height` + `overflow: hidden`, which clips content
+    // visually but leaves it in the tab order. Without this, Tab lands on a
+    // link the user cannot see, inside a box that cannot scroll to reveal it
+    // (WCAG 2.4.7 Focus Visible, 2.4.11 Focus Not Obscured). Expanding on
+    // entry keeps the focused control visible.
+    const onFocusin = event => {
+      if (item === event.target || item.contains(event.target)) return;
+      if (mgShowMoreTarget.classList.contains('mg-show-more--collapsed')) {
+        item.click();
+      }
+    };
+    mgShowMoreTarget.addEventListener('focusin', onFocusin);
 
     // Allow items to be shown by clicking anywhere on the collapsed item
     // https://gitlab.com/undrr/web-backlog/-/issues/1612
-    mgShowMoreTarget.addEventListener('click', () => {
+    const onTargetClick = () => {
       if (mgShowMoreTarget.classList.contains('mg-show-more--collapsed')) {
         item.click();
       }
-    });
+    };
+    mgShowMoreTarget.addEventListener('click', onTargetClick);
 
     item.click();
+    cleanups.push(() => {
+      item.removeEventListener('click', onClick);
+      item.removeEventListener('keydown', onKeydown);
+      mgShowMoreTarget.removeEventListener('focusin', onFocusin);
+      mgShowMoreTarget.removeEventListener('click', onTargetClick);
+      mgShowMoreTarget.classList.toggle(
+        'mg-show-more--collapsed',
+        wasCollapsed
+      );
+      item.classList.toggle('mg-show-more--button--open', wasOpen);
+      item.textContent = initialText;
+      for (const [attribute, value] of [
+        ['aria-controls', initialControls],
+        ['role', initialRole],
+      ]) {
+        if (value === null) item.removeAttribute(attribute);
+        else item.setAttribute(attribute, value);
+      }
+      delete item.dataset.mgShowMoreInitialized;
+    });
   });
+
+  return () => cleanups.splice(0).forEach(cleanup => cleanup());
 }
 
 // Auto-wrap so the browser Event object is not passed as scope