Commit 81fc1d9 h

Pat Ambrosio · 26-08-26 12:28

Collapse the page nav behind a toggle on a phone

Changes: 2 files +109 -13

Changes (Side-by-Side)

Raw

commit 81fc1d98b9b6e67362cb646ba963dbdf8c56e334
Author: Pat Ambrosio <cp.ambrosio@gmail.com>
Date:   Wed Aug 26 12:28:07 2026 +0800

    Collapse the page nav behind a toggle on a phone
    
    264px of links stood between the header and the title -- 28% of a 440px
    screen spent before the text begins. And every label wrapped: "Why this
    shape" broke across two lines at an 11px indent, which reads as two
    entries rather than one.
    
    The wrapping was a missed reset. The narrow block cleared the nav's width
    and min-width but left max-width at 6rem, so the column stayed 96px wide
    while the rest of the page went full width. All three go together now, and
    the labels fit on one line each.
    
    The nav is a <details> with a summary. The element brings its own open
    state, keyboard handling and screen reader semantics; a nav that needs
    script to open is a nav that does not open when the script fails. It ships
    open, so a wide screen renders the sidebar it always did and a failure
    leaves an expanded nav rather than a hidden one, and a line of script
    closes it on the first paint below 735px -- the same width the sidebar
    already stacks at.
    
    Two approaches were tried and rejected on evidence. Shipping it closed and
    forcing it open with CSS renders blank on desktop: a closed <details>
    suppresses painting of its contents whatever display says, so the column
    measured correct -- 96px, 7 items, first item 24px at the right offset --
    while showing nothing. And the collapse ran too early: the script is in
    <head>, so the query found no nav and the phone stayed expanded. It waits
    for DOMContentLoaded now.
    
    Collapsed, the nav is one line and the title moves from y=356 to y=128.
    Opened, it takes the full article width with no label wrapping. Desktop is
    untouched: summary hidden, sidebar visible, tops aligned at 64, body under
    title at 152.
    
    The sidebar cell is now the wrapper rather than the nav, so the :has()
    selectors and the table-cell rules move with it. Three existing tests
    caught the rename.
    
    Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
    Claude-Session: https://claude.ai/code/session_01WnSAstgnDYdKPwLGv1YZE5

diff --git a/share/jenny/layout/page.sh b/share/jenny/layout/page.sh
index 4e96dd0..ab258f6 100755
--- a/share/jenny/layout/page.sh
+++ b/share/jenny/layout/page.sh
@@ -39,6 +39,13 @@ URL_PREFIX=${URL_PREFIX:-.}
 # touching this function.
 page_nav() {
   [ -n "${PAGE_NAV:-}" ] || return 0
+  # <details> rather than a scripted toggle: the open/closed state, the
+  # keyboard handling and the screen-reader semantics are the element's own,
+  # and a nav that needs JavaScript to open is a nav that does not open when
+  # the script fails. Wide screens override it back to always-open, where a
+  # summary would be noise beside a sidebar that already fits.
+  printf '<details class="page-nav-wrap" open>\n'
+  printf '  <summary class="page-nav-toggle">Contents</summary>\n'
   printf '<nav class="page-nav">\n'
   printf '%s\n' "$PAGE_NAV" | while IFS="$(printf '\t')" read -r kind depth label path; do
     [ -n "$label" ] || continue
@@ -59,6 +66,7 @@ page_nav() {
     esac
   done
   printf '</nav>\n'
+  printf '</details>\n'
 }
 
 # diagram_script
@@ -284,7 +292,7 @@ cat << _EOF_
            74ch and the body came out 537px against a post's 540 -- a
            difference with no cause the reader could see. Widening here rather
            than narrowing the body keeps the measure identical everywhere. */
-        article:has(.page-nav) { max-width: calc(74ch + var(--page-nav-width) + var(--page-nav-gap)); }
+        article:has(.page-nav-wrap) { max-width: calc(74ch + var(--page-nav-width) + var(--page-nav-gap)); }
         /* A bare URL has no spaces to wrap at, so on a narrow screen one
            long link sets the width of the whole page -- a reference to
            https://github.com/hmngwy/jenny made this post 375px wide at a
@@ -429,11 +437,23 @@ cat << _EOF_
            width is only a suggestion, so the nav column shrank to whatever the
            longest label happened to be and the body's left edge moved with it.
            The floor keeps the column a fixed 6rem regardless of the labels. */
-        .page-nav { display: table-cell; vertical-align: top;
-                    width: var(--page-nav-width);
-                    min-width: var(--page-nav-width);
-                    max-width: var(--page-nav-width);
-                    margin: 0; padding: 0; font-size: .9em; }
+        /* The wrapper is the sidebar cell; the nav inside it is a plain
+           block. The <details> only does anything on a phone -- here the
+           summary is hidden and the element is forced open, so a wide screen
+           renders exactly the sidebar it did before. */
+        .page-nav-wrap { display: table-cell; vertical-align: top;
+                         width: var(--page-nav-width);
+                         min-width: var(--page-nav-width);
+                         max-width: var(--page-nav-width);
+                         margin: 0; padding: 0; font-size: .9em; }
+        .page-nav-toggle { display: none; }
+        /* The element ships open, so a sidebar renders on a wide screen and,
+           if the script below never runs, on a narrow one too -- failing to an
+           expanded nav rather than a hidden one. Overriding a closed
+           <details> from CSS was tried instead and does not work: a closed
+           details suppresses painting of its contents whatever display says,
+           so the column measured correct while rendering blank. */
+        .page-nav { margin: 0; padding: 0; }
         /* A label with no space in it -- a long slug, a URL -- cannot wrap, so
            the column grew to fit it and pushed the body right; min-width is a
            floor, not a ceiling. The ceiling plus overflow-wrap keeps the
@@ -489,7 +509,7 @@ cat << _EOF_
         /* With no nav there is no sidebar to sit beside, so the body starts at
            the left margin -- the same place a post's body starts now that the
            way back is below the text rather than beside it. */
-        .page-wrapper:not(:has(.page-nav)) .contents-cell { display: block;
+        .page-wrapper:not(:has(.page-nav-wrap)) .contents-cell { display: block;
                                                             padding-left: 0; }
         /* Identical to the post layout's. A block, not an inline-block: the
            body no longer sits beside anything -- the back arrow that used to
@@ -504,9 +524,24 @@ cat << _EOF_
            an anonymous table wrapper and stays in its column. */
         @media (max-width: 735px) {
           .page-wrapper,
-          .page-nav,
+          .page-nav-wrap,
           .contents-cell { display: block; }
-          .page-nav { width: auto; min-width: 0; margin-bottom: 2em; }
+          /* max-width was the reason labels wrapped at a 11px indent on a
+             phone: the narrow block reset width and min-width but left the
+             6rem ceiling in place, so the nav stayed 96px wide while the rest
+             of the page went full width. All three go together. */
+          .page-nav-wrap { width: auto; min-width: 0; max-width: none;
+                           margin-bottom: 2em; font-size: 1em; }
+          /* Collapsed by default here, and only here. A nav ahead of the text
+             costs a quarter of the screen before a reader reaches the title;
+             behind a summary it costs one line and is still one tap away. */
+
+          .page-nav-toggle { display: block; cursor: pointer;
+                             text-transform: uppercase; font-size: .9em;
+                             color: var(--text-muted); padding: .25em 0;
+                             border-bottom: 1px solid var(--border-lighter); }
+          .page-nav-toggle::marker { color: var(--text-muted); }
+          .page-nav { margin-top: .75em; }
           /* The sidebar's gap goes with the sidebar: stacked above the body,
              it is not a column to clear. Left in place it indented the body on
              a phone and forced horizontal scroll. */
@@ -609,6 +644,30 @@ cat << _EOF_
           } else if (mediaQuery.addListener) {
             mediaQuery.addListener(handleSystemChange);
           }
+          // The page nav ships open so it renders as a sidebar on a wide
+          // screen, and so that a failure here leaves an expanded nav rather
+          // than one the reader cannot open. On a narrow screen it starts
+          // collapsed: 264px of links ahead of the title is a quarter of a
+          // phone screen spent before the text begins.
+          //
+          // Closed only on the first paint at a narrow width. Re-collapsing on
+          // every resize would shut the nav under a reader who had just opened
+          // it, and matching the CSS breakpoint here keeps the two from
+          // disagreeing about what "narrow" means.
+          // Deferred: this script is in <head>, so the nav does not exist yet
+          // when it first runs -- querying for it here found nothing and the
+          // nav stayed open on a phone.
+          var collapseNav = function() {
+            var navWrap = document.querySelector('.page-nav-wrap');
+            if (navWrap && window.matchMedia('(max-width: 735px)').matches) {
+              navWrap.removeAttribute('open');
+            }
+          };
+          if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', collapseNav);
+          } else {
+            collapseNav();
+          }
           document.addEventListener('click', function(e) {
             var toggle = e.target.closest('.theme-toggle');
             if (!toggle) return;
diff --git a/test/regressions.sh b/test/regressions.sh
index c0aa821..863818c 100755
--- a/test/regressions.sh
+++ b/test/regressions.sh
@@ -1743,7 +1743,10 @@ assert_file_contains "$nav_sb/.dist/test.html" '.page-wrapper { display: table'
 assert_file_contains "$nav_sb/.dist/test.html" '.contents-cell { display: table-cell'
 
 it "the sidebar is a table cell aligned to the top of its row"
-nav_rule=$("$SED" -n '/^        \.page-nav { display: table-cell;/,/}/p' "$nav_sb/.dist/test.html")
+# The cell is the <details> wrapper now: the nav is collapsible on a phone, so
+# the sidebar column belongs to the element that holds the summary as well as
+# the list.
+nav_rule=$("$SED" -n '/^        \.page-nav-wrap { display: table-cell;/,/}/p' "$nav_sb/.dist/test.html")
 assert_contains "$nav_rule" 'vertical-align: top'
 
 it "the sidebar column does not depend on its labels"
@@ -1758,7 +1761,7 @@ it "the sidebar carries no positioning offset"
 assert_file_not_contains "$nav_sb/.dist/test.html" '.page-nav { position: absolute'
 
 it "a page with no nav takes the body indent, not the sidebar column"
-assert_file_contains "$nav_sb/.dist/plain.html" '.page-wrapper:not(:has(.page-nav))'
+assert_file_contains "$nav_sb/.dist/plain.html" '.page-wrapper:not(:has(.page-nav-wrap))'
 
 it "the body starts at the left margin, with no column reserved"
 # The indent existed only to make room for the back arrow beside the body.
@@ -1771,7 +1774,7 @@ assert_file_contains "$nav_sb/.dist/plain.html" '.home { display: block; margin-
 it "a sidebar widens the article rather than narrowing the body"
 # 74ch is sized for a post: arrow column plus a 60ch body. Letting the sidebar
 # eat into it made the body 537px against a post's 540.
-assert_file_contains "$nav_sb/.dist/test.html" 'article:has(.page-nav) { max-width: calc(74ch'
+assert_file_contains "$nav_sb/.dist/test.html" 'article:has(.page-nav-wrap) { max-width: calc(74ch'
 
 it "the body column is declared identically to a post's"
 # The user's constraint: the body of a page should differ from the body of a
@@ -1834,11 +1837,45 @@ it "narrow screens collapse the whole table, not just one cell"
 # stays in its column, so all three have to leave table layout together.
 narrow=$("$SED" -n '/@media (max-width: 735px)/,/^        }/p' "$nav_sb/.dist/test.html")
 assert_contains "$narrow" '.page-wrapper,'
-assert_contains "$narrow" '.page-nav,'
+assert_contains "$narrow" '.page-nav-wrap,'
 assert_contains "$narrow" '.contents-cell { display: block'
 
 it "the narrow sidebar releases its fixed column"
+# All three of width, min-width and max-width. The ceiling was the one left
+# behind before: the nav stayed 96px wide on a phone while the rest of the page
+# went full width, so every label wrapped at an 11px indent.
 assert_contains "$narrow" 'min-width: 0'
+assert_contains "$narrow" 'max-width: none'
+
+it "the nav is a details element, so the toggle needs no script to work"
+# <details> brings its own open/closed state, keyboard handling and screen
+# reader semantics. A nav that needs JavaScript to open is a nav that does not
+# open when the script fails.
+assert_file_contains "$nav_sb/.dist/test.html" '<details class="page-nav-wrap" open>'
+assert_file_contains "$nav_sb/.dist/test.html" '<summary class="page-nav-toggle">'
+
+it "it ships open and is closed on a phone by script"
+# Shipping open means a wide screen renders the sidebar it always did, and a
+# script failure leaves an expanded nav rather than one the reader cannot
+# reach. Overriding a closed <details> from CSS was tried first and does not
+# work -- a closed details suppresses painting of its contents whatever
+# display says, so the sidebar measured correct and rendered blank.
+assert_file_contains "$nav_sb/.dist/test.html" "matchMedia('(max-width: 735px)').matches"
+assert_file_contains "$nav_sb/.dist/test.html" "navWrap.removeAttribute('open')"
+
+it "the collapse waits for the nav to exist"
+# The script is in <head>, so it first ran before the nav was parsed: the
+# query found nothing and the nav stayed open on a phone.
+assert_file_contains "$nav_sb/.dist/test.html" "document.addEventListener('DOMContentLoaded', collapseNav)"
+
+it "the summary is hidden on a wide screen"
+# The toggle is a phone affordance; beside a sidebar that already fits it is
+# noise.
+assert_file_contains "$nav_sb/.dist/test.html" '.page-nav-toggle { display: none; }'
+
+it "a page with no nav gets no toggle"
+assert_file_not_contains "$nav_sb/.dist/plain.html" '<details class="page-nav-wrap"'
+assert_file_not_contains "$nav_sb/.dist/plain.html" '<summary'
 
 it "the build is clean for nav sidebar"
 assert_eq "$stderr_output" ""