@voidzero-dev/vitepress-theme 4.4.1 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidzero-dev/vitepress-theme",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "Shared VitePress theme for VoidZero projects",
   "type": "module",
   "license": "UNLICENSED",
@@ -15,12 +15,13 @@
     "*.css"
   ],
   "peerDependencies": {
-    "vitepress": "^2.0.0-alpha.15",
+    "vitepress": "^2.0.0-alpha.16",
     "vue": "^3.5.0"
   },
   "dependencies": {
-    "@docsearch/css": "^4.3.2",
-    "@docsearch/js": "^4.3.2",
+    "@docsearch/css": "^4.5.4",
+    "@docsearch/js": "^4.5.4",
+    "@docsearch/sidepanel-js": "^4.5.4",
     "@rive-app/canvas-lite": "^2.33.3",
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.1.18",
@@ -34,6 +35,7 @@
     "tailwindcss": "^4.1.18"
   },
   "devDependencies": {
+    "@types/mark.js": "^8.11.12",
     "typescript": "^5.9.3"
   }
 }

package/src/components/oss/Header.vue

@@ -198,7 +198,7 @@ onUnmounted(() => {
       class="wrapper px-6 py-5 flex items-center justify-between relative bg-white dark:bg-primary border-b border-stroke dark:border-nickel">
       <!-- Left side: Logo + Nav -->
       <div class="flex gap-10 self-stretch">
-        <a href="/" class="flex items-center -mx-2 px-2">
+        <a href="/" class="flex flex-col items-start justify-center -mx-2 px-2">
           <slot name="nav-bar-title-before" />
           <img class="h-4 block dark:hidden" :src="logoDark" :alt="logoAlt" />
           <img class="h-4 hidden dark:block" :src="logoLight" :alt="logoAlt" />

package/src/components/vitepress-default/VPAlgoliaSearchBox.vue

@@ -1,133 +1,238 @@
 <script setup lang="ts">
-/**
- * Forked from VitePress default theme with dynamic loading.
- *
- * Key changes from original:
- * 1. @docsearch/css and @docsearch/js are loaded dynamically (not static imports)
- * 2. This allows local search users to avoid installing docsearch packages
- * 3. Error handling prevents crashes when packages are missing or initialization fails
- */
-import { useRouter } from 'vitepress'
+import type { DocSearchInstance, DocSearchProps } from '@docsearch/js'
+import type { SidepanelInstance, SidepanelProps } from '@docsearch/sidepanel-js'
+import { inBrowser, useRouter } from 'vitepress'
 import type { DefaultTheme } from 'vitepress/theme'
-import { nextTick, onMounted, ref, watch } from 'vue'
+import { nextTick, onUnmounted, watch } from 'vue'
+import type { DocSearchAskAi } from '../../types/docsearch'
 import { useData } from '@vp-composables/data'
-import { loadDocSearchCSS, loadDocSearchJS } from '@vp-support/docsearch-loader'
+import { resolveMode, validateCredentials } from '@vp-support/docsearch'
+
+import '../../styles/vitepress-default/docsearch.css'
 
 const props = defineProps<{
-  algolia: DefaultTheme.AlgoliaSearchOptions
+  algoliaOptions: DefaultTheme.AlgoliaSearchOptions
+  openRequest?: {
+    target: 'search' | 'askAi' | 'toggleAskAi'
+    nonce: number
+  } | null
 }>()
 
 const router = useRouter()
-const { site, localeIndex, lang } = useData()
-
-// Loading state
-const isLoading = ref(true)
-const hasError = ref(false)
-let docsearchFn: ((props: any) => void) | null = null
-
-onMounted(async () => {
-  // Load CSS first
-  const cssLoaded = await loadDocSearchCSS()
-  if (!cssLoaded) {
-    hasError.value = true
-    isLoading.value = false
-    return
-  }
+const { site } = useData()
+
+let cleanup = () => {}
+let docsearchInstance: DocSearchInstance | undefined
+let sidepanelInstance: SidepanelInstance | undefined
+let openOnReady: 'search' | 'askAi' | null = null
+let initializeCount = 0
+let docsearchLoader: Promise<typeof import('@docsearch/js')> | undefined
+let sidepanelLoader: Promise<typeof import('@docsearch/sidepanel-js')> | undefined
+let lastFocusedElement: HTMLElement | null = null
+let skipEventDocsearch = false
+let skipEventSidepanel = false
+
+watch(() => props.algoliaOptions, update, { immediate: true })
+onUnmounted(cleanup)
+
+watch(
+  () => props.openRequest?.nonce,
+  () => {
+    const req = props.openRequest
+    if (!req) return
+    if (req.target === 'search') {
+      if (docsearchInstance?.isReady) {
+        onBeforeOpen('docsearch', () => docsearchInstance?.open())
+      } else {
+        openOnReady = 'search'
+      }
+    } else if (req.target === 'toggleAskAi') {
+      if (sidepanelInstance?.isOpen) {
+        sidepanelInstance.close()
+      } else {
+        onBeforeOpen('sidepanel', () => sidepanelInstance?.open())
+      }
+    } else {
+      // askAi - open sidepanel or fallback to docsearch modal
+      if (sidepanelInstance?.isReady) {
+        onBeforeOpen('sidepanel', () => sidepanelInstance?.open())
+      } else if (sidepanelInstance) {
+        openOnReady = 'askAi'
+      } else if (docsearchInstance?.isReady) {
+        onBeforeOpen('docsearch', () => docsearchInstance?.openAskAi())
+      } else {
+        openOnReady = 'askAi'
+      }
+    }
+  },
+  { immediate: true }
+)
+
+async function update(options: DefaultTheme.AlgoliaSearchOptions) {
+  if (!inBrowser) return
+  await nextTick()
 
-  // Load JS
-  docsearchFn = await loadDocSearchJS()
-  if (!docsearchFn) {
-    hasError.value = true
-    isLoading.value = false
+  const askAi = options.askAi as DocSearchAskAi | undefined
+
+  const { valid, ...credentials } = validateCredentials({
+    appId: options.appId ?? askAi?.appId,
+    apiKey: options.apiKey ?? askAi?.apiKey,
+    indexName: options.indexName ?? askAi?.indexName
+  })
+
+  if (!valid) {
+    console.warn('[vitepress] Algolia search cannot be initialized: missing appId/apiKey/indexName.')
     return
   }
 
-  isLoading.value = false
-  update()
-})
+  await initialize({ ...options, ...credentials })
+}
 
-watch(localeIndex, () => {
-  if (!isLoading.value && !hasError.value) {
-    update()
+async function initialize(userOptions: DefaultTheme.AlgoliaSearchOptions) {
+  const currentInitialize = ++initializeCount
+
+  // Always tear down previous instances first (e.g. on locale changes)
+  cleanup()
+
+  const { useSidePanel } = resolveMode(userOptions)
+  const askAi = userOptions.askAi as DocSearchAskAi | undefined
+
+  const { default: docsearch } = await loadDocsearch()
+  if (currentInitialize !== initializeCount) return
+
+  if (useSidePanel && askAi?.sidePanel) {
+    const { default: sidepanel } = await loadSidepanel()
+    if (currentInitialize !== initializeCount) return
+
+    sidepanelInstance = sidepanel({
+      ...(askAi.sidePanel === true ? {} : askAi.sidePanel),
+      container: '#vp-docsearch-sidepanel',
+      indexName: askAi.indexName ?? userOptions.indexName,
+      appId: askAi.appId ?? userOptions.appId,
+      apiKey: askAi.apiKey ?? userOptions.apiKey,
+      assistantId: askAi.assistantId,
+      onOpen: focusInput,
+      onClose: onClose.bind(null, 'sidepanel'),
+      onReady: () => {
+        if (openOnReady === 'askAi') {
+          openOnReady = null
+          onBeforeOpen('sidepanel', () => sidepanelInstance?.open())
+        }
+      },
+      keyboardShortcuts: {
+        'Ctrl/Cmd+I': false
+      }
+    } as SidepanelProps)
   }
-})
 
-async function update() {
-  if (!docsearchFn) return
-
-  await nextTick()
   const options = {
-    ...props.algolia,
-    ...props.algolia.locales?.[localeIndex.value]
-  }
-  const rawFacetFilters = options.searchParameters?.facetFilters ?? []
-  const facetFilters = [
-    ...(Array.isArray(rawFacetFilters)
-      ? rawFacetFilters
-      : [rawFacetFilters]
-    ).filter((f) => !f.startsWith('lang:')),
-    `lang:${lang.value}`
-  ]
-
-  // Rebuild the askAi prop as an object:
-  // If the askAi prop is a string, treat it as the assistantId and use
-  // the default indexName, apiKey and appId from the main options.
-  // If the askAi prop is an object, spread its explicit values.
-  const askAiProp = options.askAi
-  const isAskAiString = typeof askAiProp === 'string'
-
-  const askAi = askAiProp
-    ? {
-        indexName: isAskAiString ? options.indexName : askAiProp.indexName,
-        apiKey: isAskAiString ? options.apiKey : askAiProp.apiKey,
-        appId: isAskAiString ? options.appId : askAiProp.appId,
-        assistantId: isAskAiString ? askAiProp : askAiProp.assistantId,
-        // Re-use the merged facetFilters from the search parameters so that
-        // Ask AI uses the same language filtering as the regular search.
-        searchParameters: facetFilters.length ? { facetFilters } : undefined
+    ...userOptions,
+    container: '#vp-docsearch',
+    navigator: {
+      navigate(item) {
+        router.go(item.itemUrl)
       }
-    : undefined
-
-  initialize({
-    ...options,
-    searchParameters: {
-      ...options.searchParameters,
-      facetFilters
     },
-    askAi
+    transformItems: (items) => items.map((item) => ({ ...item, url: getRelativePath(item.url) })),
+    // When sidepanel is enabled, intercept Ask AI events to open it instead (hybrid mode)
+    ...(useSidePanel && sidepanelInstance && {
+      interceptAskAiEvent: (initialMessage) => {
+        onBeforeOpen('sidepanel', () => sidepanelInstance?.open(initialMessage))
+        return true
+      }
+    }),
+    onOpen: focusInput,
+    onClose: onClose.bind(null, 'docsearch'),
+    onReady: () => {
+      if (openOnReady === 'search') {
+        openOnReady = null
+        onBeforeOpen('docsearch', () => docsearchInstance?.open())
+      } else if (openOnReady === 'askAi' && !sidepanelInstance) {
+        // No sidepanel configured, use docsearch modal for askAi
+        openOnReady = null
+        onBeforeOpen('docsearch', () => docsearchInstance?.openAskAi())
+      }
+    },
+    keyboardShortcuts: {
+      '/': false,
+      'Ctrl/Cmd+K': false
+    }
+  } as DocSearchProps
+
+  docsearchInstance = docsearch(options)
+
+  cleanup = () => {
+    docsearchInstance?.destroy()
+    sidepanelInstance?.destroy()
+    docsearchInstance = undefined
+    sidepanelInstance = undefined
+    openOnReady = null
+    lastFocusedElement = null
+  }
+}
+
+function focusInput() {
+  requestAnimationFrame(() => {
+    const input =
+      document.querySelector<HTMLInputElement>('#docsearch-input') ||
+      document.querySelector<HTMLInputElement>('#docsearch-sidepanel textarea')
+    input?.focus()
   })
 }
 
-function initialize(userOptions: DefaultTheme.AlgoliaSearchOptions) {
-  if (!docsearchFn) {
-    console.error('[VitePress Theme] DocSearch not loaded')
-    return
+function onBeforeOpen(target: 'docsearch' | 'sidepanel', cb: () => void) {
+  if (target === 'docsearch') {
+    if (sidepanelInstance?.isOpen) {
+      skipEventSidepanel = true
+      sidepanelInstance.close()
+    } else if (!docsearchInstance?.isOpen) {
+      if (document.activeElement instanceof HTMLElement) {
+        lastFocusedElement = document.activeElement
+      }
+    }
+  } else if (target === 'sidepanel') {
+    if (docsearchInstance?.isOpen) {
+      skipEventDocsearch = true
+      docsearchInstance.close()
+    } else if (!sidepanelInstance?.isOpen) {
+      if (document.activeElement instanceof HTMLElement) {
+        lastFocusedElement = document.activeElement
+      }
+    }
   }
+  setTimeout(cb, 0)
+}
 
-  try {
-    const options = Object.assign({}, userOptions, {
-      container: '#docsearch',
-
-      navigator: {
-        navigate(item: { itemUrl: string }) {
-          router.go(item.itemUrl)
-        }
-      },
+function onClose(target: 'docsearch' | 'sidepanel') {
+  if (target === 'docsearch') {
+    if (skipEventDocsearch) {
+      skipEventDocsearch = false
+      return
+    }
+  } else if (target === 'sidepanel') {
+    if (skipEventSidepanel) {
+      skipEventSidepanel = false
+      return
+    }
+  }
+  if (lastFocusedElement) {
+    lastFocusedElement.focus()
+    lastFocusedElement = null
+  }
+}
 
-      transformItems(items: { url: string }[]) {
-        return items.map((item) => {
-          return Object.assign({}, item, {
-            url: getRelativePath(item.url)
-          })
-        })
-      }
-    })
+function loadDocsearch() {
+  if (!docsearchLoader) {
+    docsearchLoader = import('@docsearch/js')
+  }
+  return docsearchLoader
+}
 
-    docsearchFn(options as any)
-  } catch (error) {
-    console.error('[VitePress Theme] Failed to initialize DocSearch:', error)
-    hasError.value = true
+function loadSidepanel() {
+  if (!sidepanelLoader) {
+    sidepanelLoader = import('@docsearch/sidepanel-js')
   }
+  return sidepanelLoader
 }
 
 function getRelativePath(url: string) {
@@ -137,6 +242,6 @@ function getRelativePath(url: string) {
 </script>
 
 <template>
-  <!-- Render nothing on error - search fails silently -->
-  <div v-if="!hasError" id="docsearch" />
+  <div id="vp-docsearch" />
+  <div id="vp-docsearch-sidepanel" />
 </template>

package/src/components/vitepress-default/VPLocalSearchBox.vue

@@ -6,7 +6,7 @@
  */
 import {
   computedAsync,
-  debouncedWatch,
+  watchDebounced,
   onKeyStroke,
   useEventListener,
   useLocalStorage,
@@ -35,23 +35,7 @@ import { escapeRegExp } from '@vp-support/shared-utils'
 import { useData } from '@vp-composables/data'
 import { LRUCache } from '@vp-support/lru'
 import { createSearchTranslate } from '@vp-support/translation'
-
-// Modal translations type
-interface ModalTranslations {
-  displayDetails?: string
-  resetButtonTitle?: string
-  backButtonTitle?: string
-  noResultsText?: string
-  footer?: {
-    selectText?: string
-    selectKeyAriaLabel?: string
-    navigateText?: string
-    navigateUpKeyAriaLabel?: string
-    navigateDownKeyAriaLabel?: string
-    closeText?: string
-    closeKeyAriaLabel?: string
-  }
-}
+import type { LocalSearchTranslations } from '../../types/local-search'
 
 const emit = defineEmits<{
   (e: 'close'): void
@@ -177,16 +161,6 @@ const disableDetailedView = computed(() => {
   )
 })
 
-const buttonText = computed(() => {
-  const options = theme.value.search?.options ?? theme.value.algolia
-
-  return (
-    options?.locales?.[localeIndex.value]?.translations?.button?.buttonText ||
-    options?.translations?.button?.buttonText ||
-    'Search'
-  )
-})
-
 watchEffect(() => {
   if (disableDetailedView.value) {
     showDetailedList.value = false
@@ -208,7 +182,7 @@ const mark = computedAsync(async () => {
 
 const cache = new LRUCache<string, Map<string, string>>(16) // 16 files
 
-debouncedWatch(
+watchDebounced(
   () => [searchIndex.value, filterText.value, showDetailedList.value] as const,
   async ([index, filterTextValue, showDetailedListValue], old, onCleanup) => {
     if (old?.[0] !== index) {
@@ -404,7 +378,10 @@ onKeyStroke('Escape', () => {
 })
 
 // Translations
-const defaultTranslations: { modal: ModalTranslations } = {
+const defaultTranslations: LocalSearchTranslations = {
+  button: {
+    buttonText: 'Search'
+  },
   modal: {
     displayDetails: 'Display detailed list',
     resetButtonTitle: 'Reset search',
@@ -424,7 +401,7 @@ const defaultTranslations: { modal: ModalTranslations } = {
 
 const translate = createSearchTranslate(defaultTranslations)
 
-// Back
+/* Back */
 
 onMounted(() => {
   // Prevents going to previous site
@@ -437,6 +414,7 @@ useEventListener('popstate', (event) => {
 })
 
 /** Lock body */
+
 const isLocked = useScrollLock(inBrowser ? document.body : null)
 
 onMounted(() => {
@@ -514,7 +492,7 @@ function onMouseMove(e: MouseEvent) {
             @submit.prevent=""
           >
             <label
-              :title="buttonText"
+              :title="translate('button.buttonText')"
               id="localsearch-label"
               for="localsearch-input"
             >
@@ -543,7 +521,7 @@ function onMouseMove(e: MouseEvent) {
               id="localsearch-input"
               enterkeyhint="go"
               maxlength="64"
-              :placeholder="buttonText"
+              :placeholder="translate('button.buttonText')"
               spellcheck="false"
               type="search"
             />

package/src/components/vitepress-default/VPMenuLink.vue

@@ -7,6 +7,7 @@ import VPLink from './VPLink.vue'
 
 const props = defineProps<{
   item: T
+  rel?: string
 }>()
 
 const { page } = useData()
@@ -34,7 +35,7 @@ defineOptions({ inheritAttrs: false })
       }"
       :href
       :target="item.target"
-      :rel="item.rel"
+      :rel="props.rel ?? item.rel"
       :no-icon="item.noIcon"
     >
       <span v-html="item.text"></span>

package/src/components/vitepress-default/VPNavBar.vue

@@ -1,6 +1,5 @@
 <script lang="ts" setup>
 import { useWindowScroll } from '@vueuse/core'
-import { ref, watchPostEffect } from 'vue'
 import { useLayout } from '@vp-composables/layout'
 import VPNavBarSearch from './VPNavBarSearch.vue'
 import VPNavBarAppearance from './VPNavBarAppearance.vue'
@@ -21,21 +20,18 @@ defineEmits<{
 
 const { y } = useWindowScroll()
 const { isHome, hasSidebar } = useLayout()
-
-const classes = ref<Record<string, boolean>>({})
-
-watchPostEffect(() => {
-  classes.value = {
-    'has-sidebar': hasSidebar.value,
-    'home': isHome.value,
-    'top': y.value === 0,
-    'screen-open': props.isScreenOpen
-  }
-})
 </script>
 
 <template>
-  <div class="VPNavBar" :class="classes">
+  <div
+    class="VPNavBar"
+    :class="{
+      'has-sidebar': hasSidebar,
+      'home': isHome,
+      'top': y === 0,
+      'screen-open': isScreenOpen
+    }"
+  >
     <div class="wrapper">
       <div class="container">
         <div class="title">
@@ -55,7 +51,11 @@ watchPostEffect(() => {
             <VPNavBarSocialLinks class="social-links" />
             <VPNavBarExtra class="extra" />
             <slot name="nav-bar-content-after" />
-            <VPNavBarHamburger class="hamburger" :active="isScreenOpen" @click="$emit('toggle-screen')" />
+            <VPNavBarHamburger
+              class="hamburger"
+              :active="isScreenOpen"
+              @click="$emit('toggle-screen')"
+            />
           </div>
         </div>
       </div>
@@ -203,12 +203,6 @@ watchPostEffect(() => {
   }
 }
 
-@media (max-width: 767px) {
-  .content-body {
-    column-gap: 0.5rem;
-  }
-}
-
 .menu + .translations::before,
 .menu + .appearance::before,
 .menu + .social-links::before,

package/src/components/vitepress-default/VPNavBarAskAiButton.vue

@@ -0,0 +1,31 @@
+<template>
+  <button type="button" class="VPNavBarAskAiButton">
+    <span class="vpi-sparkles" aria-hidden="true"></span>
+  </button>
+</template>
+
+<style scoped>
+.VPNavBarAskAiButton {
+  display: flex;
+  align-items: center;
+  height: var(--vp-nav-height);
+  padding: 8px 14px;
+  font-size: 20px;
+}
+
+@media (min-width: 768px) {
+  .VPNavBarAskAiButton {
+    height: auto;
+    padding: 11.5px;
+    transition: color 0.3s ease;
+    background-color: var(--vp-c-bg-alt);
+    border-radius: 8px;
+    font-size: 15px;
+    color: var(--vp-c-text-2);
+  }
+
+  .VPNavBarAskAiButton:hover {
+    color: var(--vp-c-brand-1);
+  }
+}
+</style>

package/src/components/vitepress-default/VPNavBarExtra.vue

@@ -34,7 +34,13 @@ const hasExtraContent = computed(
       <p class="trans-title">{{ currentLang.label }}</p>
 
       <template v-for="locale in localeLinks" :key="locale.link">
-        <VPMenuLink :item="locale" :lang="locale.lang" :dir="locale.dir" />
+        <VPMenuLink
+          :item="locale"
+          :lang="locale.lang"
+          :hreflang="locale.lang"
+          rel="alternate"
+          :dir="locale.dir"
+        />
       </template>
     </div>