fix(theme): stabilize palette selector without instant navigation

[claudiacodacy]

Summary

• reserve a fixed palette-control slot so light/dark changes do not collapse or move the header
• keep header controls above the search backdrop while search is open
• remove redundant palette initialization and use one-time, full-page-load initialization for theme scripts

Validation

• mkdocs build --strict --clean --site-dir /tmp/docs-theme-selector-site
• browser-tested against production and a local build at desktop and 390px mobile widths
• verified full-page navigation keeps the selected scheme and navigation.instant remains disabled

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[gemini-code-assist]

Code Review

This pull request refactors the theme's JavaScript initialization to use standard DOMContentLoaded events instead of the document$ subscription, improves search input focusing by replacing setTimeout with requestAnimationFrame, and updates header and palette CSS styling. The feedback highlights a leftover argument in the requestAnimationFrame call and redundant flex properties applied to a grid item in the stylesheet.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[codacy-production]

Pull Request Overview

This PR stabilizes the header layout by reserving fixed dimensions for the theme palette toggle and adjusting z-index levels to maintain navigation visibility during search. The implementation is up to standards according to Codacy, and complexity has been reduced in the version selection logic.

The most critical change is the transition from document$.subscribe to standard DOMContentLoaded events. While this fulfills the current requirement to stabilize initialization, it explicitly breaks compatibility with MkDocs Material's 'instant navigation' feature. If that feature is ever re-enabled, page-specific JavaScript will fail to re-initialize during client-side transitions.

About this PR

• The removal of 'document$.subscribe' explicitly breaks support for MkDocs Material's 'navigation.instant' feature. If this feature is re-enabled in the future, custom theme functionality (search shortcuts, version selector) will fail to re-initialize on secondary page loads.

1 comment outside of the diff

docs/assets/javascripts/docs-theme.js

_{line 63 ⚪ LOW RISK}
Suggestion: The refactor to requestAnimationFrame left a trailing , 0 argument at the end of the callback on line 63. While browser execution might ignore it, it should be removed for correctness.

    });

Test suggestions

• Verify palette container and button styles use fixed widths (2.25rem) and flex-basis to prevent layout collapse.
• Verify header inner children (excluding search) are elevated to z-index 101 when the search toggle is checked.
• Ensure docs-theme.js initialization logic correctly handles both 'loading' and 'interactive/complete' document ready states.
• Verify search input focus is managed via requestAnimationFrame and includes cleanup for pending frames.
• Confirm the removal of partials/javascripts/palette.html to reduce redundant initialization.

_{TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback}