Fix toggles (#2428)

Fixes impl-variant toggle behavior in regards to:
- layout shift on load
- outline inconsistencies (both node and java headers shown on load)

Good page for testing:
http://localhost:5173/docs/guides/databases/postgres#deploy
Chrome Performance CLS: 0.01 -> 0.00

---------

Co-authored-by: Christian Georgi <[email protected]>

Author: Akatuoro

.vitepress/config.js

@@ -76,7 +76,8 @@ const config = defineConfig({
     ['link', { rel: 'icon', href: base+'favicon.ico' }],
     ['link', { rel: 'shortcut icon', href: base+'favicon.ico' }],
     ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: base+'logos/cap.png' }],
-    ['script', { src: base+'script.js' } ]
+    // Inline script to restore impl-variant selection immediately (before first paint)
+    ['script', { id: 'check-impl-variant' }, `{const p=new URLSearchParams(location.search),v=p.get('impl-variant')||localStorage.getItem('impl-variant');if(v)document.documentElement.classList.add(v)}`]
   ],
 
   vite: {

.vitepress/theme/Layout.vue

@@ -1,4 +1,5 @@
 <script lang="ts" setup>
+import { onMounted } from 'vue'
 import { useData } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import ShortcutsList from './components/ShortcutsList.vue'
@@ -13,6 +14,12 @@ const archiveVersion = import.meta.env.VITE_CAPIRE_VERSION
 const { Layout } = DefaultTheme
 const { frontmatter } = useData()
 
+onMounted(() => {
+  // Enable transitions after hydration to prevent flickering during initial load
+  requestAnimationFrame(() => {
+    document.documentElement.classList.add('transitions-ready')
+  })
+})
 </script>
 
 <template>

.vitepress/theme/components/implvariants/ImplVariants.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { onMounted, computed, ref, watchEffect } from 'vue'
+import { onMounted, onUnmounted, computed, ref, watch } from 'vue'
 import { useData } from 'vitepress'
 import VPSwitch from '../VPSwitch.vue'
 import IconNode from './IconNode.vue'
@@ -11,26 +11,33 @@ const checked = ref(false)
 const toggle = typeof localStorage !== 'undefined' ? useVariant() : () => {}
 const knownImplVariants = ['node', 'java']
 
+let outlineObserver = null
+
 onMounted(() => {
   if (!supportsVariants.value) return
 
-  let check = currentCheckState()
-  // Persist value even intially. If query param was used, users expect to get this value from now on, even if not using the query anymore.
+  const check = currentCheckState()
+  // Persist value initially. If query param was used, users expect to get this value from now on.
   const variantNew = check ? 'java' : 'node'
   localStorage.setItem('impl-variant', variantNew)
 
-  setClass(check)
+  syncState(check)
+  observeOutline()
+})
 
-  // Scroll hash element into view. Needed on first page load if variant is changed by query param.
-  scrollTo(window.location.hash?.slice(1))
+onUnmounted(() => {
+  if (outlineObserver) {
+    outlineObserver.disconnect()
+    outlineObserver = null
+  }
 })
 
-function scrollTo(id) {
-  const elem = document.getElementById(id)
-  if (elem) {
-    setTimeout(() => { elem?.scrollIntoView(true) }, 20)
+watch(supportsVariants, (supports) => {
+  if (supports) {
+    syncState(currentCheckState())
+    observeOutline()
   }
-}
+})
 
 function currentCheckState() {
   const url = new URL(window.location)
@@ -39,76 +46,61 @@ function currentCheckState() {
   return localStorage.getItem('impl-variant') === 'java'
 }
 
-function setClass(check) {
+function syncState(check) {
   checked.value = check
 
-  for (let swtch of document.getElementsByClassName('SwitchImplVariant')) {
-    swtch.classList[check ? 'add' : 'remove']('checked')
+  for (const swtch of document.getElementsByClassName('SwitchImplVariant')) {
+    swtch.classList.toggle('checked', check)
   }
-  for (let container of document.getElementsByClassName('SwitchImplVariantContainer')) {
+  for (const container of document.getElementsByClassName('SwitchImplVariantContainer')) {
     container.title = check ? 'Java content. Toggle to see Node.js.' : 'Node.js content. Toggle to see Java.'
   }
 
   markOutlineItems()
-  toggleContent(check ? 'java' : 'node')
-
 }
 
 function useVariant() {
   function toggle() {
     let check = currentCheckState()
-    setClass((check = !check))
+    check = !check
+
     const variantNew = check ? 'java' : 'node'
     localStorage.setItem('impl-variant', variantNew)
 
+    toggleContent(variantNew)
+    syncState(check)
+
     if (supportsVariants.value) {
       const url = new URL(window.location)
       url.searchParams.set('impl-variant', variantNew)
       window.history.replaceState({}, '', url)
     }
-
   }
   return toggle
 }
 
-function animationsOff(cb) {
-  let css
-  css = document.createElement('style')
-  css.appendChild(
-    document.createTextNode(
-    `:not(.VPSwitchAppearance):not(.VPSwitchAppearance *) {
--webkit-transition: none !important;
--moz-transition: none !important;
--o-transition: none !important;
--ms-transition: none !important;
-transition: none !important;
-}`
-  ))
-  document.head.appendChild(css)
-
-  cb()
-
-  // keep unused declaration, used to force the browser to redraw
-  // eslint-disable-next-line no-unused-vars
-  const _ = window.getComputedStyle(css).opacity
-  document.head.removeChild(css)
-}
-
-watchEffect(() => {
-  if (!supportsVariants.value) return
-  setTimeout(() => { // otherwise DOM is not ready
-    if (typeof document !== 'undefined') {
-      animationsOff(() => setClass(currentCheckState()) )
-    }
-  }, 20)
-})
-
 function toggleContent(variant) {
   const htmlClassList = document.documentElement.classList
   knownImplVariants.forEach(v => htmlClassList.remove(v))
   htmlClassList.add(variant)
 }
 
+function observeOutline() {
+  if (outlineObserver) return
+
+  const aside = document.querySelector('.VPDocAside')
+  if (!aside) return
+
+  markOutlineItems()
+  outlineObserver = new MutationObserver(() => {
+    markOutlineItems()
+  })
+  outlineObserver.observe(aside, {
+    childList: true,
+    subtree: true
+  })
+}
+
 // Only mark outline items here, as these are not part of the generated HTML,
 // but are created on the fly with JS.
 // All other DOM content is handled at build time on MD level (see md-attrs-propagate.ts)

.vitepress/theme/styles.scss

@@ -10,6 +10,16 @@
 html {
   &.java .node { display: none; }
   &.node .java { display: none; }
+
+  :not(.transitions-ready) {
+    :not(.VPSwitchAppearance):not(.VPSwitchAppearance *) {
+      -webkit-transition: none !important;
+      -moz-transition: none !important;
+      -o-transition: none !important;
+      -ms-transition: none !important;
+      transition: none !important;
+    }
+  }
 }