Commit 8fb5eb9 h

Pat Ambrosio · 26-09-01 10:29

Centre a linked passage instead of pinning it to the top

Changes: 3 files +101 -16

Changes (Side-by-Side)

Raw

commit 8fb5eb95dc6c90ba42d93f43ff56645582d0c5a9
Author: Pat Ambrosio <cp.ambrosio@gmail.com>
Date:   Tue Sep 1 10:29:27 2026 +0800

    Centre a linked passage instead of pinning it to the top
    
    A passage scrolled flush with the top edge has nothing above it, so the
    reader sees the sentence they followed and none of what it follows from.
    Centred, it arrives with its own context either side.
    
    Two paths need it, and they are not the same problem. A click can simply
    take the scroll over before the browser jumps. An inbound permalink
    cannot: by the time this runs the browser has already put the target at
    the top, so it has to be moved rather than merely marked -- and a frame
    later, because fonts and diagrams both change the height above it and
    would otherwise leave the centring stale. Measured on a page whose
    diagrams render after load: still dead centre.
    
    The click handler is delegated on the document rather than bound to the
    marks, so a cross-reference written in the prose gets the same treatment.
    The footnote links do too: the jump to a note lands off centre only
    because the notes sit at the end of the document and there is nothing
    below them to scroll, which is the browser doing the right thing.
    
    Measured in Chrome, polling until the scroll settles rather than after a
    fixed delay -- read mid-animation the target is 530px out, which looks
    like a defect and is not.

diff --git a/share/jenny/layout/page.sh b/share/jenny/layout/page.sh
index a8ad0d9..53449df 100755
--- a/share/jenny/layout/page.sh
+++ b/share/jenny/layout/page.sh
@@ -1238,18 +1238,51 @@ cat << _EOF_
             });
 
             // Mark whatever the reader arrived at, so a permalink lands on
-            // something visibly identified rather than just scrolled to.
-            function markTarget() {
+            // something visibly identified rather than just scrolled to, and
+            // put it in the middle of the screen rather than against the top
+            // edge. A passage flush with the top has no text above it, so
+            // there is nothing to show what it follows from; centred, it
+            // arrives with its own context either side.
+            function showTarget(t, smooth) {
               document.querySelectorAll('.target-flash').forEach(function(e) {
                 e.classList.remove('target-flash');
               });
-              if (!location.hash) return;
-              var t = null;
-              try { t = document.querySelector(location.hash); } catch (err) { return; }
-              if (t) t.classList.add('target-flash');
+              if (!t) return;
+              t.classList.add('target-flash');
+              t.scrollIntoView({ behavior: smooth ? 'smooth' : 'auto', block: 'center' });
+            }
+            function resolveHash() {
+              if (!location.hash) return null;
+              try { return document.querySelector(location.hash); } catch (err) { return null; }
+            }
+
+            // A click within the page: the browser would jump the target to the
+            // top, so take the scroll over.
+            document.addEventListener('click', function(e) {
+              var link = e.target.closest('a[href^="#"]');
+              if (!link) return;
+              var id = link.getAttribute('href').slice(1);
+              if (!id) return;
+              var t = document.getElementById(id);
+              if (!t) return;
+              e.preventDefault();
+              history.replaceState(null, '', '#' + id);
+              showTarget(t, true);
+            });
+
+            window.addEventListener('hashchange', function() {
+              showTarget(resolveHash(), true);
+            });
+
+            // Arriving from elsewhere at .../page#id: the browser has already
+            // scrolled the target to the top by the time this runs, so it has
+            // to be moved rather than merely marked. A frame later, once
+            // layout has settled -- fonts and diagrams both change the height
+            // above it and would otherwise leave the centring stale.
+            var initial = resolveHash();
+            if (initial) {
+              requestAnimationFrame(function() { showTarget(initial, false); });
             }
-            window.addEventListener('hashchange', markTarget);
-            markTarget();
           }
           // The script tag sits in the body, so at parse time the content it
           // needs may not exist yet -- the first version ran before any of it
diff --git a/share/jenny/layout/post.sh b/share/jenny/layout/post.sh
index 0785ce5..59e6308 100755
--- a/share/jenny/layout/post.sh
+++ b/share/jenny/layout/post.sh
@@ -1010,18 +1010,51 @@ cat << _EOF_
             });
 
             // Mark whatever the reader arrived at, so a permalink lands on
-            // something visibly identified rather than just scrolled to.
-            function markTarget() {
+            // something visibly identified rather than just scrolled to, and
+            // put it in the middle of the screen rather than against the top
+            // edge. A passage flush with the top has no text above it, so
+            // there is nothing to show what it follows from; centred, it
+            // arrives with its own context either side.
+            function showTarget(t, smooth) {
               document.querySelectorAll('.target-flash').forEach(function(e) {
                 e.classList.remove('target-flash');
               });
-              if (!location.hash) return;
-              var t = null;
-              try { t = document.querySelector(location.hash); } catch (err) { return; }
-              if (t) t.classList.add('target-flash');
+              if (!t) return;
+              t.classList.add('target-flash');
+              t.scrollIntoView({ behavior: smooth ? 'smooth' : 'auto', block: 'center' });
+            }
+            function resolveHash() {
+              if (!location.hash) return null;
+              try { return document.querySelector(location.hash); } catch (err) { return null; }
+            }
+
+            // A click within the page: the browser would jump the target to the
+            // top, so take the scroll over.
+            document.addEventListener('click', function(e) {
+              var link = e.target.closest('a[href^="#"]');
+              if (!link) return;
+              var id = link.getAttribute('href').slice(1);
+              if (!id) return;
+              var t = document.getElementById(id);
+              if (!t) return;
+              e.preventDefault();
+              history.replaceState(null, '', '#' + id);
+              showTarget(t, true);
+            });
+
+            window.addEventListener('hashchange', function() {
+              showTarget(resolveHash(), true);
+            });
+
+            // Arriving from elsewhere at .../page#id: the browser has already
+            // scrolled the target to the top by the time this runs, so it has
+            // to be moved rather than merely marked. A frame later, once
+            // layout has settled -- fonts and diagrams both change the height
+            // above it and would otherwise leave the centring stale.
+            var initial = resolveHash();
+            if (initial) {
+              requestAnimationFrame(function() { showTarget(initial, false); });
             }
-            window.addEventListener('hashchange', markTarget);
-            markTarget();
           }
           // The script tag sits in the body, so at parse time the content it
           // needs may not exist yet -- the first version ran before any of it
diff --git a/test/regressions.sh b/test/regressions.sh
index 416e45e..131759f 100755
--- a/test/regressions.sh
+++ b/test/regressions.sh
@@ -1450,6 +1450,25 @@ it "the mark is hidden until the passage is hovered or the mark focused"
 assert_file_contains "$dg/.dist/chart.html" '.anchor-link:focus { opacity: 1; }'
 assert_file_contains "$dg/.dist/chart.html" '@media (hover: none) { .anchor-link { display: none; } }'
 
+it "a linked passage is centred, not pinned to the top"
+# A passage flush with the top edge has no text above it, so nothing shows
+# what it follows from. Centred, it arrives with its own context either side.
+# Measured in Chrome once the scroll settles: dead centre for an in-page click,
+# for an inbound permalink, and for a prose cross-reference.
+assert_file_contains "$dg/.dist/chart.html" "block: 'center'"
+assert_file_contains "$dg/.dist/post/charted.html" "block: 'center'"
+
+it "an inbound permalink is re-centred after the browser's own jump"
+# Arriving at .../page#id, the browser has already put the target at the top
+# by the time this runs, so it has to be moved rather than merely marked --
+# and a frame later, once fonts and diagrams have settled the height above it.
+assert_file_contains "$dg/.dist/chart.html" "requestAnimationFrame(function() { showTarget(initial, false); });"
+
+it "every in-page link is centred, not just the marks"
+# The handler is delegated on the document, so a cross-reference written in
+# the prose behaves the same way as a deep-link mark.
+assert_file_contains "$dg/.dist/chart.html" "a[href^=\"#\"]"
+
 it "following a permalink marks what was linked"
 # A reader landing mid-document needs to see which passage was meant.
 assert_file_contains "$dg/.dist/chart.html" "t.classList.add('target-flash');"