Skip to content

Commit

Permalink
doc: improve fragment (:target) anchors behavior on HTML version
Browse files Browse the repository at this point in the history
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: #42739
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information
aduh95 authored and targos committed Apr 28, 2022
1 parent 459546b commit d77c59d
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 12 deletions.
44 changes: 32 additions & 12 deletions doc/api_assets/api.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
);
}
}

Expand Down Expand Up @@ -60,7 +64,7 @@
for (const picker of pickers) {
const parentNode = picker.parentNode;

picker.addEventListener('click', (e) => {
picker.addEventListener('click', function(e) {
e.preventDefault();

/*
Expand All @@ -76,7 +80,7 @@
to close pickers if needed.
*/

requestAnimationFrame(() => {
requestAnimationFrame(function() {
parentNode.classList.add('expanded');
window.addEventListener('click', closeAllPickers);
window.addEventListener('keydown', onKeyDown);
Expand All @@ -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) {
Expand All @@ -109,7 +113,7 @@
The timer is reset anyway after few milliseconds.
*/
ignoreNextIntersection = true;
setTimeout(() => {
setTimeout(function() {
ignoreNextIntersection = false;
}, 50);

Expand All @@ -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') {
Expand Down
11 changes: 11 additions & 0 deletions doc/api_assets/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down

0 comments on commit d77c59d

Please sign in to comment.