fix: preserve side tools state across navigation

- Keep the tools menu choice during single-page navigation
- Hide side tools accessibly and recalc visibility on resize
- Stack the expanded menu above the gear button without slide animation

Author: evannotfound

docs/content/docs/en/basic/global.mdx

@@ -172,7 +172,9 @@ Controls whether the gear icon in the right-bottom tools rotates continuously.
 | :---: | :---: | :---: |
 | Boolean | `true \| false` | `false` |
 
-Controls whether the side tools list automatically expands when the page loads. By default, users need to click the gear button to reveal the tools list.
+Controls whether the side tools list starts expanded on a full page load. Users
+can toggle the list with the gear button, and their choice is preserved while
+navigating with the single-page experience.
 
 ## Google Analytics
 

docs/content/docs/zh/basic/global.mdx

@@ -171,7 +171,7 @@ description: 设置全站的一些功能。
 | :----: | :-------------: | :-----: |
 | 布尔值 | `true \| false` | `false` |
 
-控制侧边工具列表是否在页面加载时自动展开。默认情况下，用户需要点击齿轮按钮才能显示工具列表。
+控制侧边工具列表是否在完整加载页面时默认展开。用户可以点击齿轮按钮切换显示状态，使用单页导航时会保留当前选择。
 
 ## Google Analytics
 

layout/components/side-tools.ejs

@@ -1,43 +1,43 @@
 <%
-    const toolClass = "mb-1 flex size-10 shrink-0 cursor-pointer items-center justify-center rounded-2xl border border-rd-gray-alpha-400 bg-rd-background-100 text-lg text-rd-gray-1000 shadow-rd last:mb-0 hover:!bg-primary hover:!text-rd-primary-text sm:size-11 sm:text-xl [&_i]:!text-inherit";
+    const toolClass = "flex size-10 shrink-0 items-center justify-center rounded-2xl border border-rd-gray-alpha-400 bg-rd-background-100 text-lg text-rd-gray-1000 shadow-rd hover:!bg-primary hover:!text-rd-primary-text sm:size-11 sm:text-xl [&_i]:!text-inherit";
 %>
-<div>
-    <div id="side-tools-menu" data-state="closed" class="translate-x-full opacity-0 transition-[transform,opacity] duration-200 ease-in-out data-[state=open]:translate-x-0 data-[state=open]:opacity-100">
-        <button id="theme-toggle" data-side-tool type="button" class="<%= toolClass %>" aria-label="<%= __('theme') %>" title="<%= __('theme') %>">
-            <i class="fa-regular fa-moon" aria-hidden="true"></i>
-        </button>
+<div class="flex flex-col items-end gap-1">
+    <div class="relative">
+        <div id="side-tools-menu" data-state="closed" aria-hidden="true" class="invisible absolute right-0 bottom-full mb-1 flex flex-col gap-1 opacity-0 pointer-events-none transition-opacity duration-200 ease-in-out data-[state=open]:visible data-[state=open]:opacity-100 data-[state=open]:pointer-events-auto motion-reduce:transition-none">
+            <button id="theme-toggle" data-side-tool type="button" class="<%= toolClass %>" aria-label="<%= __('theme') %>" title="<%= __('theme') %>">
+                <i class="fa-regular fa-moon" aria-hidden="true"></i>
+            </button>
 
-        <% if (theme.plugins.feed.enable && config.feed) { %>
-            <a data-side-tool class="<%= toolClass %>" href="<%= url_for(config.feed.path) %>" target="_blank" rel="noopener noreferrer" aria-label="<%= __('rss_feed') %>" title="<%= __('rss_feed') %>">
-                <i class="fa-regular fa-rss" aria-hidden="true"></i>
-            </a>
-        <% } %>
+            <% if (theme.plugins.feed.enable && config.feed) { %>
+                <a data-side-tool class="<%= toolClass %>" href="<%= url_for(config.feed.path) %>" target="_blank" rel="noopener noreferrer" aria-label="<%= __('rss_feed') %>" title="<%= __('rss_feed') %>">
+                    <i class="fa-regular fa-rss" aria-hidden="true"></i>
+                </a>
+            <% } %>
 
-        <% if (theme.global.scroll_progress.percentage !== true) { %>
-            <button id="scroll-top" data-side-tool type="button" class="<%= toolClass %>" aria-label="<%= __('top') %>" title="<%= __('top') %>">
-                <i class="fa-regular fa-arrow-up" aria-hidden="true"></i>
-            </button>
-        <% } %>
+            <% if (theme.global.scroll_progress.percentage !== true) { %>
+                <button id="scroll-top" data-side-tool type="button" class="<%= toolClass %>" aria-label="<%= __('top') %>" title="<%= __('top') %>">
+                    <i class="fa-regular fa-arrow-up" aria-hidden="true"></i>
+                </button>
+            <% } %>
 
-        <button id="scroll-bottom" data-side-tool type="button" class="<%= toolClass %>" aria-label="Bottom" title="Bottom">
-            <i class="fa-regular fa-arrow-down" aria-hidden="true"></i>
-        </button>
-    </div>
+            <button id="scroll-bottom" data-side-tool type="button" class="<%= toolClass %>" aria-label="Bottom" title="Bottom">
+                <i class="fa-regular fa-arrow-down" aria-hidden="true"></i>
+            </button>
+        </div>
 
-    <div>
         <button id="side-tools-toggle" data-side-tool type="button" class="<%= toolClass %>" aria-controls="side-tools-menu" aria-expanded="false" aria-label="Tools" title="Tools">
             <i class="fa-regular fa-cog <% if (theme.global.side_tools && theme.global.side_tools.gear_rotation !== false) { %>fa-spin<% } %>" aria-hidden="true"></i>
         </button>
-        <% if (theme.global.scroll_progress.percentage === true) { %>
-            <button id="scroll-top" data-side-tool type="button" data-state="hidden" class="group <%= toolClass %> data-[state=hidden]:hidden" aria-label="<%= __('top') %>" title="<%= __('top') %>">
-                <i data-scroll-arrow class="fas fa-arrow-up !hidden group-hover:!flex" aria-hidden="true"></i>
-                <span data-scroll-percent class="flex text-base group-hover:!hidden"></span>
-            </button>
-        <% } %>
-        <% if (theme.plugins.aplayer.enable && theme.plugins.aplayer.type === "mini") { %>
-            <div class="hidden md:block">
-                <div data-side-tool class="<%= toolClass %>" aria-hidden="true"></div>
-            </div>
-        <% } %>
     </div>
+
+    <% if (theme.global.scroll_progress.percentage === true) { %>
+        <button id="scroll-top" data-side-tool type="button" data-state="hidden" class="group <%= toolClass %> data-[state=hidden]:hidden" aria-label="<%= __('top') %>" title="<%= __('top') %>">
+            <i data-scroll-arrow class="fas fa-arrow-up !hidden group-hover:!flex" aria-hidden="true"></i>
+            <span data-scroll-percent class="flex text-base group-hover:!hidden"></span>
+        </button>
+    <% } %>
+
+    <% if (theme.plugins.aplayer.enable && theme.plugins.aplayer.type === "mini") { %>
+        <div class="hidden size-10 sm:size-11 md:block" aria-hidden="true"></div>
+    <% } %>
 </div>

layout/page.ejs

@@ -24,7 +24,7 @@
 
 	<%- partial('pages/router', {pageKind: currentPageKind, region: 'after-shell'}) %>
 
-	<aside id="side-tools" data-state="visible" class="fixed right-3 bottom-6 z-30 opacity-100 transition-opacity duration-200 data-[state=hidden]:pointer-events-none data-[state=hidden]:opacity-0 sm:right-10">
+	<aside id="side-tools" data-state="visible" class="fixed right-3 bottom-6 z-30 opacity-100 transition-opacity duration-200 data-[state=hidden]:pointer-events-none data-[state=hidden]:opacity-0 motion-reduce:transition-none sm:right-10">
 		<%- partial('components/side-tools') %>
 	</aside>
 

source/js/utils.js

@@ -45,6 +45,7 @@ const registerScrollHandlers = (signal) => {
 
   didInitScroll = true;
   window.addEventListener("scroll", handleScroll, { signal });
+  window.addEventListener("resize", handleScroll, { signal });
   window.addEventListener("scroll", debounce(handleHomeBannerBlur, 20), {
     signal,
   });

source/js/utils/sideTools.js

@@ -1,6 +1,8 @@
+let toolsMenuOpen = theme.global.side_tools?.auto_expand === true;
+
 export const updateAutoHideTools = () => {
   const y = window.scrollY;
-  const height = document.body.scrollHeight;
+  const height = document.documentElement.scrollHeight;
   const windowHeight = window.innerHeight;
   const tools = document.getElementById("side-tools");
   const aplayer = document.getElementById("aplayer");
@@ -9,27 +11,38 @@ export const updateAutoHideTools = () => {
     return;
   }
 
+  const isScrollable = height > windowHeight;
   const shouldHide =
     (y <= 100 && location.pathname === config.root) ||
-    y + windowHeight >= height - 20;
-  tools.dataset.state = shouldHide ? "hidden" : "visible";
-  aplayer?.classList.toggle("hide", shouldHide);
+    (isScrollable && y + windowHeight >= height - 20);
+  const state = shouldHide ? "hidden" : "visible";
+
+  if (tools.dataset.state !== state) {
+    tools.dataset.state = state;
+    tools.setAttribute("aria-hidden", String(shouldHide));
+    tools.inert = shouldHide;
+  }
+  if (aplayer && aplayer.classList.contains("hide") !== shouldHide) {
+    aplayer.classList.toggle("hide", shouldHide);
+  }
 };
 
 export const initToolsListToggle = (ctx, signal) => {
   if (!ctx?.toolsList || !ctx?.toggleButton) {
     return;
   }
 
-  if (theme.global.side_tools && theme.global.side_tools.auto_expand) {
-    ctx.toolsList.dataset.state = "open";
-    ctx.toggleButton.setAttribute("aria-expanded", "true");
-  }
+  const applyState = () => {
+    ctx.toolsList.dataset.state = toolsMenuOpen ? "open" : "closed";
+    ctx.toolsList.setAttribute("aria-hidden", String(!toolsMenuOpen));
+    ctx.toggleButton.setAttribute("aria-expanded", String(toolsMenuOpen));
+  };
+
+  applyState();
 
   const handler = () => {
-    const isOpen = ctx.toolsList.dataset.state === "open";
-    ctx.toolsList.dataset.state = isOpen ? "closed" : "open";
-    ctx.toggleButton.setAttribute("aria-expanded", String(!isOpen));
+    toolsMenuOpen = !toolsMenuOpen;
+    applyState();
   };
 
   if (signal) {

tests/theme-generation.test.mjs

@@ -62,11 +62,18 @@ test("theme build and generation configurations", async (t) => {
       "data-sidebar-panel",
       'class="order-last rounded-2xl border',
       'aria-label="Theme Redefine" class="order-first overflow-hidden',
-      'class="flex w-full items-center gap-2 rounded-lg',
+      "data-sidebar-link",
       'id="page-shell"',
       'id="main-content"',
       'id="site-footer"',
+      'id="side-tools" data-state="visible" class="fixed',
+      'class="flex flex-col items-end gap-1"',
+      'id="side-tools-menu" data-state="closed" aria-hidden="true" class="invisible absolute right-0 bottom-full mb-1 flex flex-col gap-1 opacity-0 pointer-events-none transition-opacity',
     ]);
+    const sideToolsMenu = home.match(/<div id="side-tools-menu"[^>]+>/)?.[0] || "";
+    assert.ok(!sideToolsMenu.includes("translate-x"));
+    assert.ok(!sideToolsMenu.includes("transition-[transform,opacity]"));
+    assert.ok(!home.includes('data-side-tool class="hidden size-10'));
     assert.equal(home.split('href="/essays"').length, 3);
     includes(post, ['id="article-layout"', 'id="toc-toggle"']);
     [home, post].forEach((output) => {