feat(theme): expose `useSidebar` (#2496)

Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>

__tests__/unit/vitest.config.ts

@@ -1,17 +1,26 @@
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { defineConfig } from 'vitest/config'
+import vue from '@vitejs/plugin-vue'
 
 const dir = dirname(fileURLToPath(import.meta.url))
 
 export default defineConfig({
+  plugins: [vue()],
   resolve: {
-    alias: {
-      '@siteData': resolve(dir, './shims.ts'),
-      client: resolve(dir, '../../src/client'),
-      node: resolve(dir, '../../src/node'),
-      vitepress: resolve(dir, '../../src/client')
-    }
+    alias: [
+      { find: '@siteData', replacement: resolve(dir, './shims.ts') },
+      { find: 'client', replacement: resolve(dir, '../../src/client') },
+      { find: 'node', replacement: resolve(dir, '../../src/node') },
+      {
+        find: /^vitepress$/,
+        replacement: resolve(dir, '../../src/client/index.js')
+      },
+      {
+        find: /^vitepress\/theme$/,
+        replacement: resolve(dir, '../../src/client/theme-default/index.js')
+      }
+    ]
   },
   test: {
     globals: true

docs/reference/default-theme-sidebar.md

@@ -180,3 +180,36 @@ export default {
   }
 }
 ```
+
+## `useSidebar` <Badge type="info" text="composable" />
+
+Returns sidebar-related data. The returned object has the following type:
+
+```ts
+export interface Sidebar {
+  isOpen: Ref<boolean>
+  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
+  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
+  hasSidebar: ComputedRef<boolean>
+  hasAside: ComputedRef<boolean>
+  leftAside: ComputedRef<boolean>
+  isSidebarEnabled: ComputedRef<boolean>
+  open: () => void
+  close: () => void
+  toggle: () => void
+}
+```
+
+**Example:**
+
+```vue
+<script setup>
+import { useSidebar } from 'vitepress/theme'
+
+const { hasSidebar } = useSidebar()
+</script>
+
+<template>
+  <div v-if="hasSidebar">Only show when sidebar exists</div>
+</template>
+```

src/client/theme-default/Layout.vue

@@ -1,15 +1,16 @@
 <script setup lang="ts">
-import { computed, provide, useSlots, watch } from 'vue'
 import { useRoute } from 'vitepress'
-import { useData } from './composables/data'
-import { useSidebar, useCloseSidebarOnEscape } from './composables/sidebar'
-import VPSkipLink from './components/VPSkipLink.vue'
+import { useSidebar } from 'vitepress/theme'
+import { computed, provide, useSlots, watch } from 'vue'
 import VPBackdrop from './components/VPBackdrop.vue'
-import VPNav from './components/VPNav.vue'
-import VPLocalNav from './components/VPLocalNav.vue'
-import VPSidebar from './components/VPSidebar.vue'
 import VPContent from './components/VPContent.vue'
 import VPFooter from './components/VPFooter.vue'
+import VPLocalNav from './components/VPLocalNav.vue'
+import VPNav from './components/VPNav.vue'
+import VPSidebar from './components/VPSidebar.vue'
+import VPSkipLink from './components/VPSkipLink.vue'
+import { useData } from './composables/data'
+import { useCloseSidebarOnEscape } from './composables/sidebar'
 
 const {
   isOpen: isSidebarOpen,
@@ -56,7 +57,7 @@ provide('hero-image-slot-exists', heroImageSlotExists)
     <VPContent>
       <template #page-top><slot name="page-top" /></template>
       <template #page-bottom><slot name="page-bottom" /></template>
-      
+
       <template #not-found><slot name="not-found" /></template>
       <template #home-hero-before><slot name="home-hero-before" /></template>
       <template #home-hero-info><slot name="home-hero-info" /></template>

src/client/theme-default/components/VPContent.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
+import { useSidebar } from 'vitepress/theme'
+import NotFound from '../NotFound.vue'
 import { useData } from '../composables/data'
-import { useSidebar } from '../composables/sidebar'
-import VPPage from './VPPage.vue'
-import VPHome from './VPHome.vue'
 import VPDoc from './VPDoc.vue'
-import NotFound from '../NotFound.vue'
+import VPHome from './VPHome.vue'
+import VPPage from './VPPage.vue'
 
 const { page, frontmatter } = useData()
 const { hasSidebar } = useSidebar()

src/client/theme-default/components/VPDoc.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { useRoute } from 'vitepress'
+import { useSidebar } from 'vitepress/theme'
 import { computed } from 'vue'
-import { useSidebar } from '../composables/sidebar'
 import VPDocAside from './VPDocAside.vue'
 import VPDocFooter from './VPDocFooter.vue'
 import VPDocOutlineDropdown from './VPDocOutlineDropdown.vue'

src/client/theme-default/components/VPFooter.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
+import { useSidebar } from 'vitepress/theme'
 import { useData } from '../composables/data'
-import { useSidebar } from '../composables/sidebar'
 
 const { theme } = useData()
 const { hasSidebar } = useSidebar()

src/client/theme-default/components/VPLocalNav.vue

@@ -1,10 +1,10 @@
 <script lang="ts" setup>
 import { useWindowScroll } from '@vueuse/core'
-import { computed, shallowRef } from 'vue'
 import { onContentUpdated } from 'vitepress'
+import { useSidebar } from 'vitepress/theme'
+import { computed, shallowRef } from 'vue'
 import { useData } from '../composables/data'
 import { getHeaders, type MenuItem } from '../composables/outline'
-import { useSidebar } from '../composables/sidebar'
 import VPLocalNavOutlineDropdown from './VPLocalNavOutlineDropdown.vue'
 import VPIconAlignLeft from './icons/VPIconAlignLeft.vue'
 

src/client/theme-default/components/VPNavBar.vue

@@ -1,15 +1,15 @@
 <script lang="ts" setup>
-import { computed } from 'vue'
 import { useWindowScroll } from '@vueuse/core'
-import { useSidebar } from '../composables/sidebar'
-import VPNavBarTitle from './VPNavBarTitle.vue'
-import VPNavBarSearch from './VPNavBarSearch.vue'
-import VPNavBarMenu from './VPNavBarMenu.vue'
-import VPNavBarTranslations from './VPNavBarTranslations.vue'
+import { useSidebar } from 'vitepress/theme'
+import { computed } from 'vue'
 import VPNavBarAppearance from './VPNavBarAppearance.vue'
-import VPNavBarSocialLinks from './VPNavBarSocialLinks.vue'
 import VPNavBarExtra from './VPNavBarExtra.vue'
 import VPNavBarHamburger from './VPNavBarHamburger.vue'
+import VPNavBarMenu from './VPNavBarMenu.vue'
+import VPNavBarSearch from './VPNavBarSearch.vue'
+import VPNavBarSocialLinks from './VPNavBarSocialLinks.vue'
+import VPNavBarTitle from './VPNavBarTitle.vue'
+import VPNavBarTranslations from './VPNavBarTranslations.vue'
 
 defineProps<{
   isScreenOpen: boolean

src/client/theme-default/components/VPNavBarTitle.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
+import { useSidebar } from 'vitepress/theme'
 import { useData } from '../composables/data'
-import { useSidebar } from '../composables/sidebar'
 import { useLangs } from '../composables/langs'
 import { normalizeLink } from '../support/utils'
 import VPImage from './VPImage.vue'

src/client/theme-default/components/VPSidebar.vue

@@ -1,7 +1,7 @@
 <script lang="ts" setup>
+import { clearAllBodyScrollLocks, disableBodyScroll } from 'body-scroll-lock'
+import { useSidebar } from 'vitepress/theme'
 import { ref, watchPostEffect } from 'vue'
-import { disableBodyScroll, clearAllBodyScrollLocks } from 'body-scroll-lock'
-import { useSidebar } from '../composables/sidebar'
 import VPSidebarItem from './VPSidebarItem.vue'
 
 const { sidebarGroups, hasSidebar } = useSidebar()

src/client/theme-default/composables/aside.ts

@@ -1,6 +1,6 @@
-import { computed } from 'vue'
 import { useMediaQuery } from '@vueuse/core'
-import { useSidebar } from './sidebar'
+import { useSidebar } from 'vitepress/theme'
+import { computed } from 'vue'
 
 export function useAside() {
   const { hasSidebar } = useSidebar()

src/client/theme-default/without-fonts.ts

@@ -23,6 +23,8 @@ export { default as VPTeamPageTitle } from './components/VPTeamPageTitle.vue'
 export { default as VPTeamPageSection } from './components/VPTeamPageSection.vue'
 export { default as VPTeamMembers } from './components/VPTeamMembers.vue'
 
+export { useSidebar } from './composables/sidebar'
+
 const theme: Theme = {
   Layout,
   enhanceApp: ({ app }) => {

theme.d.ts

@@ -14,9 +14,10 @@ export const VPTeamMembers: DefineComponent
 
 declare const theme: {
   Layout: DefineComponent
-  NotFound: DefineComponent
   enhanceApp: (ctx: EnhanceAppContext) => void
 }
 
 export default theme
 export type { DefaultTheme } from './types/default-theme.js'
+
+export const useSidebar: () => DefaultTheme.SideBar

types/default-theme.d.ts

@@ -209,6 +209,22 @@ export namespace DefaultTheme {
     collapsed?: boolean
   }
 
+  /**
+   * ReturnType of `useSidebar`
+   */
+  export interface Sidebar {
+    isOpen: Ref<boolean>
+    sidebar: ComputedRef<SidebarItem[]>
+    sidebarGroups: ComputedRef<SidebarItem[]>
+    hasSidebar: ComputedRef<boolean>
+    hasAside: ComputedRef<boolean>
+    leftAside: ComputedRef<boolean>
+    isSidebarEnabled: ComputedRef<boolean>
+    open: () => void
+    close: () => void
+    toggle: () => void
+  }
+
   // edit link -----------------------------------------------------------------
 
   export interface EditLink {