diff --git a/CHANGES.rst b/CHANGES.rst index 1adacce4..0d87feeb 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5,6 +5,7 @@ CHANGES Unreleased ---------- +- Bugfix for TOC expand/collapse not working well across projects. 2026/01/08 0.46.0 ----------------- @@ -15,6 +16,9 @@ Unreleased navigation enhancements. Originally introduced in 0.43.0, reverted in 0.44.0. - CrateDB Npgsql docs were removed. +This release was yanked, because the navigation didn't work across projects and +couldn't be tested locally. + 2025/12/19 0.45.0 ----------------- - Reverted silencing build warnings, because it made the navigation bar look odd. diff --git a/docs/tests/index.rst b/docs/tests/index.rst index 099165ab..ff940e83 100644 --- a/docs/tests/index.rst +++ b/docs/tests/index.rst @@ -4,12 +4,31 @@ Navigation bar test pages ######################### -1. Clicking the title should expand the section and navigate to the section page -2. Clicking just the icon should expand but not navigate to the section -3. Clicking just the icon for an expanded section should collapse that section and leave other expanded sections expanded -4. Hovering the mouse over an icon should show a fade background behind the icon -5. Hovering the mouse over the title should show a fade background behind the title and the icon -6. The current page should be highlighted in the navigation bar as the user navigates through the pages below. +**Same-project entries (entries with actual TOC content):** + +1. Clicking the title expands the section, collapses sibling sections at the + same level, and navigates to the section page +2. Clicking just the icon expands/collapses that section without navigating +3. Clicking the icon for an expanded section collapses it, leaving other + expanded sections unchanged + +**Cross-project entries (entries linking to other projects):** + +4. Clicking the title navigates to that project +5. Clicking just the icon also navigates to that project (since the TOC + content from another project isn't available to expand) + +**Visual feedback:** + +6. Hovering the mouse over an icon shows a fade background behind the icon +7. Hovering the mouse over the title shows a fade background behind the title + and the icon +8. The current page is highlighted in the navigation bar + +**Auto-expansion:** + +9. The Database Drivers section auto-expands when viewing a driver project + (only on first visit; user preference is respected thereafter) **Pages:** diff --git a/src/crate/theme/rtd/crate/static/js/custom.js b/src/crate/theme/rtd/crate/static/js/custom.js index 4d2a829e..ed542ff7 100644 --- a/src/crate/theme/rtd/crate/static/js/custom.js +++ b/src/crate/theme/rtd/crate/static/js/custom.js @@ -79,25 +79,85 @@ document.addEventListener('DOMContentLoaded', () => { // Restore state on page load restoreNavState(); + // Auto-expand sections marked with data-auto-expand="true" + // Used for Database Drivers when viewing a driver project. + // Only auto-expand if user hasn't explicitly set a preference for this checkbox. + const savedStates = localStorage.getItem('navState'); + let userPreferences = {}; + if (savedStates) { + try { + userPreferences = JSON.parse(savedStates); + } catch (e) { + // Ignore parse errors, treat as no preferences + } + } + let autoExpandStateChanged = false; + + document.querySelectorAll('[data-auto-expand="true"]').forEach((li) => { + const checkbox = li.querySelector('.toctree-checkbox'); + if (checkbox && checkbox.id) { + // Only auto-expand if user has no saved preference for this checkbox + if (!(checkbox.id in userPreferences)) { + checkbox.checked = true; + autoExpandStateChanged = true; + } + } + }); + + // Save the auto-expanded state so it persists + if (autoExpandStateChanged) { + saveNavState(); + } + // Save state when checkboxes change document.querySelectorAll('.toctree-checkbox').forEach((checkbox) => { checkbox.addEventListener('change', saveNavState); }); - // Make clicking the link text expand the section if collapsed, then navigate - // Design: Click expands collapsed sections AND navigates to the page. - // Already-expanded sections just navigate (no toggle). This allows users to - // expand nested navigation while browsing, without collapsing sections they - // want to keep visible. + // Make clicking the link text expand the section and collapse siblings. + // This provides consistent UX: clicking any title shows only that section's + // children, matching what happens with cross-project navigation. document.querySelectorAll('.bs-docs-sidenav li.has-children > a, .bs-docs-sidenav li.has-children > .reference').forEach((link) => { link.addEventListener('click', () => { const li = link.parentElement; const checkbox = li.querySelector('.toctree-checkbox'); - if (checkbox && !checkbox.checked) { - // Only expand if collapsed - navigation proceeds regardless + + // Collapse sibling sections at the same level + const parent = li.parentElement; + if (parent) { + parent.querySelectorAll(':scope > li.has-children > .toctree-checkbox').forEach((siblingCheckbox) => { + if (siblingCheckbox !== checkbox && siblingCheckbox.checked) { + siblingCheckbox.checked = false; + } + }); + } + + // Expand this section + if (checkbox) { checkbox.checked = true; - saveNavState(); } + + saveNavState(); + }); + }); + + // Cross-project navigation: clicking expand icon on entries with empty