From 3cd3a6af8b65bdbce9e5d6d84fad80e2f9677d17 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 17 Apr 2022 16:51:42 +0200
Subject: [PATCH] doc: improve fragment (`:target`) anchors behavior on HTML
 version
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This commit aims to improve the UX when navigating the docs using links
to subsections. Previously the browser would scroll down to the section
body, skipping the section heading. Using `scroll-margin-top` CSS
property, we can fix this behavior (at least on some browsers).

Links to other versions are now updated with the current targeted hash
to improve the UX when navigating from docs of one release line to
another.

I've also removed syntax not parsable by older browsers (arrow functions
and array destructuring) since the diff is pretty small and should
improve UX on those browsers.

PR-URL: https://github.com/nodejs/node/pull/42739
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api_assets/api.js    | 44 +++++++++++++++++++++++++++++-----------
 doc/api_assets/style.css | 11 ++++++++++
 2 files changed, 43 insertions(+), 12 deletions(-)

diff --git a/doc/api_assets/api.js b/doc/api_assets/api.js
index 4304a254600da8..8854182c4c56f0 100644
--- a/doc/api_assets/api.js
+++ b/doc/api_assets/api.js
@@ -15,9 +15,13 @@
         }
         mq.addEventListener('change', mqChangeListener);
         if (themeToggleButton) {
-          themeToggleButton.addEventListener('click', function() {
-            mq.removeEventListener('change', mqChangeListener);
-          }, { once: true });
+          themeToggleButton.addEventListener(
+            'click',
+            function() {
+              mq.removeEventListener('change', mqChangeListener);
+            },
+            { once: true }
+          );
         }
       }
 
@@ -60,7 +64,7 @@
     for (const picker of pickers) {
       const parentNode = picker.parentNode;
 
-      picker.addEventListener('click', (e) => {
+      picker.addEventListener('click', function(e) {
         e.preventDefault();
 
         /*
@@ -76,7 +80,7 @@
           to close pickers if needed.
         */
 
-        requestAnimationFrame(() => {
+        requestAnimationFrame(function() {
           parentNode.classList.add('expanded');
           window.addEventListener('click', closeAllPickers);
           window.addEventListener('keydown', onKeyDown);
@@ -90,9 +94,9 @@
     let ignoreNextIntersection = false;
 
     new IntersectionObserver(
-      ([e]) => {
+      function(e) {
         const currentStatus = header.classList.contains('is-pinned');
-        const newStatus = e.intersectionRatio < 1;
+        const newStatus = e[0].intersectionRatio < 1;
 
         // Same status, do nothing
         if (currentStatus === newStatus) {
@@ -109,7 +113,7 @@
           The timer is reset anyway after few milliseconds.
         */
         ignoreNextIntersection = true;
-        setTimeout(() => {
+        setTimeout(function() {
           ignoreNextIntersection = false;
         }, 50);
 
@@ -119,18 +123,34 @@
     ).observe(header);
   }
 
+  function setupAltDocsLink() {
+    const linkWrapper = document.getElementById('alt-docs');
+
+    function updateHashes() {
+      for (const link of linkWrapper.querySelectorAll('a')) {
+        link.hash = location.hash;
+      }
+    }
+
+    addEventListener('hashchange', updateHashes);
+    updateHashes();
+  }
+
   function bootstrap() {
-    // Check if we have JavaScript support
+    // Check if we have JavaScript support.
     document.documentElement.classList.add('has-js');
 
-    // Restore user mode preferences
+    // Restore user mode preferences.
     setupTheme();
 
-    // Handle pickers with click/taps rather than hovers
+    // Handle pickers with click/taps rather than hovers.
     setupPickers();
 
-    // Track when the header is in sticky position
+    // Track when the header is in sticky position.
     setupStickyHeaders();
+
+    // Make link to other versions of the doc open to the same hash target (if it exists).
+    setupAltDocsLink();
   }
 
   if (document.readyState === 'loading') {
diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css
index 14302edc061a1d..c567fbed1c23d4 100644
--- a/doc/api_assets/style.css
+++ b/doc/api_assets/style.css
@@ -40,6 +40,17 @@
   --color-text-secondary: var(--green2);
 }
 
+h4 :target,
+h5 :target {
+  scroll-margin-top: 55px;
+}
+
+@supports not (content-visibility: auto) {
+  h3 :target {
+    scroll-margin-top: 55px;
+  }
+}
+
 .dark-mode {
   --background-color-highlight: var(--black2);
   --color-critical: var(--red4);