docs: integrate useStack and Scrim across overlay components

- Install createStackPlugin in plugins/zero.ts for SSR-safe stack context
- Unify scroll lock in default.vue via stack.isActive watch
- Add Scrim with teleport=false to share stacking context with overlays
- Register AppNav, AppSettingsSheet, DocsSearch with stack for z-index coordination
- Add conditional stack registration to DocsAsk for mobile modal mode
- Use isolated createStack() in StackProvider example to avoid global interference
- Fix use-stack.md API docs to show correct register/select/unselect pattern
- Fix scrim.md custom stack example to use provide() instead of non-existent prop
- Simplify StackConsumer escape handler to stack.top.value?.dismiss()

Author: johnleider

apps/docs/src/components/app/AppNav.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
   // Framework
-  import { IN_BROWSER, useClickOutside, useFeatures, useWindowEventListener } from '@vuetify/v0'
+  import { IN_BROWSER, useClickOutside, useFeatures, useStack, useWindowEventListener } from '@vuetify/v0'
 
   // Components
   import { Discovery } from '@/components/discovery'
@@ -24,6 +24,7 @@
 
   const settings = useSettings()
   const devmode = useFeatures().get('devmode')!
+  const stack = useStack()
 
   const app = useAppStore()
   const navigation = useNavigation()
@@ -94,6 +95,16 @@
   onMounted(updateMobile)
   useWindowEventListener('resize', updateMobile, { passive: true })
 
+  // Register with stack for z-index coordination (mobile only)
+  const ticket = stack.register({
+    onDismiss: () => navigation.close(),
+  })
+
+  watch(() => navigation.isOpen.value && isMobile.value, isOpen => {
+    if (isOpen) ticket.select()
+    else ticket.unselect()
+  }, { immediate: true })
+
   // Scroll active link into view after nav sections are ready
   watch(scrollEnabled, enabled => {
     if (!enabled || !IN_BROWSER) return
@@ -137,14 +148,15 @@
     as="nav"
     class="flex flex-col fixed w-[230px] py-4 top-0 md:top-[72px] bottom-0"
     :class="[
-      'flex flex-col fixed w-[230px] overflow-y-auto py-4 top-0 md:top-[72px] bottom-0 translate-x-[-100%] md:translate-x-0 border-r border-solid border-divider z-50',
+      'flex flex-col fixed w-[230px] overflow-y-auto py-4 top-0 md:top-[72px] bottom-0 translate-x-[-100%] md:translate-x-0 border-r border-solid border-divider',
       settings.showBgGlass.value ? 'bg-glass-surface' : 'bg-surface',
       navigation.isOpen.value && '!translate-x-0',
       !settings.prefersReducedMotion.value && 'transition-transform duration-200 ease-in-out',
     ]"
     :inert="!navigation.isOpen.value && isMobile ? true : undefined"
     :padding="-4"
     step="navigation"
+    :style="{ zIndex: ticket.zIndex.value }"
   >
     <!-- Mobile header -->
     <header class="md:hidden shrink-0 px-4 py-3 -mt-4 mb-4 border-b border-divider flex items-center justify-between bg-surface">

apps/docs/src/components/app/AppSettingsSheet.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
   // Framework
-  import { useFeatures, useStorage } from '@vuetify/v0'
+  import { useFeatures, useStack, useStorage } from '@vuetify/v0'
 
   // Composables
   import { useCustomThemes } from '@/composables/useCustomThemes'
@@ -14,6 +14,17 @@
   const storage = useStorage()
   const settings = useSettings()
   const levelFilter = useLevelFilterContext()
+  const stack = useStack()
+
+  // Register with stack for z-index coordination
+  const ticket = stack.register({
+    onDismiss: () => settings.close(),
+  })
+
+  watch(settings.isOpen, isOpen => {
+    if (isOpen) ticket.select()
+    else ticket.unselect()
+  }, { immediate: true })
 
   const hasChanges = computed(() => settings.hasChanges.value || levelFilter.hasChanges.value)
 
@@ -57,8 +68,9 @@
     ref="sheet"
     aria-labelledby="settings-title"
     aria-modal="true"
-    :class="['fixed inset-y-0 right-0 flex flex-col z-50 w-[320px] max-w-full shadow-xl outline-none', settings.showBgGlass.value ? 'bg-glass-surface' : 'bg-surface']"
+    :class="['fixed inset-y-0 right-0 flex flex-col w-[320px] max-w-full shadow-xl outline-none', settings.showBgGlass.value ? 'bg-glass-surface' : 'bg-surface']"
     role="dialog"
+    :style="{ zIndex: ticket.zIndex.value }"
     tabindex="-1"
     @keydown="onKeydown"
   >

apps/docs/src/components/docs/DocsAsk.vue

@@ -1,14 +1,13 @@
 <script setup lang="ts">
   // Framework
-  import { useBreakpoints, useDocumentEventListener } from '@vuetify/v0'
+  import { useBreakpoints, useDocumentEventListener, useStack, useToggleScope } from '@vuetify/v0'
 
   // Components
   import DocsAskInput from './DocsAskInput.vue'
   import DocsAskPanel from './DocsAskPanel.vue'
 
   // Composables
   import { useAsk } from '@/composables/useAsk'
-  import { useScrollLock } from '@/composables/useScrollLock'
   import { useSettings } from '@/composables/useSettings'
 
   // Utilities
@@ -20,16 +19,32 @@
   const isDesktop = computed(() => breakpoints.lgAndUp.value)
   const fullscreen = shallowRef(false)
   const settings = useSettings()
+  const stack = useStack()
 
-  const fadeTransition = toRef(() => settings.prefersReducedMotion.value ? undefined : 'fade')
   const panelTransition = toRef(() => {
     if (settings.prefersReducedMotion.value) return undefined
     return isDesktop.value ? 'fade' : 'slide'
   })
 
   const ask = useAsk()
 
-  useScrollLock(() => ask.isOpen.value && fullscreen.value && isDesktop.value)
+  // Register with stack only in mobile modal mode (not desktop floating panel)
+  const stackZIndex = shallowRef<number | undefined>(undefined)
+
+  useToggleScope(() => !isDesktop.value, () => {
+    const ticket = stack.register({
+      onDismiss: () => ask.close(),
+    })
+
+    watch(ask.isOpen, isOpen => {
+      if (isOpen) ticket.select()
+      else ticket.unselect()
+    }, { immediate: true })
+
+    watch(ticket.zIndex, z => {
+      stackZIndex.value = z
+    }, { immediate: true })
+  })
 
   const panelRef = useTemplateRef<InstanceType<typeof DocsAskPanel>>('panel')
   const triggerRef = shallowRef<HTMLElement | null>(null)
@@ -91,15 +106,6 @@
     @submit="onSubmit"
   />
 
-  <!-- Backdrop (mobile only) -->
-  <Transition :name="fadeTransition">
-    <div
-      v-if="ask.isOpen.value && !isDesktop"
-      class="fixed inset-0 bg-black/30 z-40"
-      @click="ask.close"
-    />
-  </Transition>
-
   <!-- Chat panel -->
   <Transition :name="panelTransition">
     <DocsAskPanel
@@ -109,6 +115,7 @@
       :error="ask.error.value"
       :is-loading="ask.isLoading.value"
       :messages="ask.messages.value"
+      :z-index="stackZIndex"
       @clear="ask.clear"
       @close="ask.close"
       @stop="ask.stop"

apps/docs/src/components/docs/DocsAskPanel.vue

@@ -24,6 +24,7 @@
     isLoading: boolean
     error: string | null
     fullscreen?: boolean
+    zIndex?: number
   }>()
 
   const emit = defineEmits<{
@@ -146,7 +147,7 @@
     aria-labelledby="ask-title"
     :aria-modal="!isDesktop"
     :class="[
-      'flex flex-col z-50',
+      'flex flex-col',
       settings.showBgGlass.value ? 'bg-glass-surface' : 'bg-surface',
       isDesktop && fullscreen
         ? 'fixed inset-4 rounded-lg border border-divider shadow-lg'
@@ -155,6 +156,7 @@
           : 'fixed inset-0',
     ]"
     :role="isDesktop ? 'complementary' : 'dialog'"
+    :style="{ zIndex: props.zIndex ?? 50 }"
   >
     <!-- Header -->
     <Discovery.Activator

apps/docs/src/components/docs/DocsSearch.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
   // Framework
-  import { useDocumentEventListener } from '@vuetify/v0'
+  import { useDocumentEventListener, useStack } from '@vuetify/v0'
 
   // Components
   import { Discovery } from '@/components/discovery'
@@ -20,6 +20,17 @@
 
   const search = useSearch()
   const discovery = useDiscovery()
+  const stack = useStack()
+
+  // Register with stack for z-index coordination
+  const ticket = stack.register({
+    onDismiss: () => search.close(),
+  })
+
+  watch(search.isOpen, isOpen => {
+    if (isOpen) ticket.select()
+    else ticket.unselect()
+  }, { immediate: true })
 
   const router = useRouter()
   const inputRef = useTemplateRef<HTMLInputElement>('input')
@@ -138,21 +149,14 @@
 </script>
 
 <template>
-  <Transition :name="transition">
-    <div
-      v-if="search.isOpen.value"
-      class="fixed inset-0 bg-black/30 z-50"
-      @click="search.close"
-    />
-  </Transition>
-
   <Transition :name="transition">
     <div
       v-if="search.isOpen.value"
       aria-label="Search Documentation"
       aria-modal="true"
-      class="fixed inset-x-0 top-[20%] mx-auto w-full max-w-2xl z-50 px-4"
+      class="fixed inset-x-0 top-[20%] mx-auto w-full max-w-2xl px-4"
       role="dialog"
+      :style="{ zIndex: ticket.zIndex.value }"
     >
       <div :class="['rounded-lg shadow-xl border border-divider overflow-hidden', settings.showBgGlass.value ? 'bg-glass-surface' : 'bg-surface']">
         <Discovery.Activator

apps/docs/src/examples/composables/use-stack/StackConsumer.vue

@@ -45,10 +45,7 @@
 
   // Escape key dismisses the topmost non-blocking overlay
   useHotkey('Escape', () => {
-    const topTicket = tickets.find(t => t.ticket.globalTop.value)
-    if (topTicket && !topTicket.overlay.blocking) {
-      close(topTicket.overlay.id)
-    }
+    stack.top.value?.dismiss()
   })
 </script>
 

apps/docs/src/examples/composables/use-stack/StackProvider.vue

@@ -2,12 +2,14 @@
   // Note: For SSR applications, install the plugin in main.ts:
   // import { createStackPlugin } from '@vuetify/v0'
   // app.use(createStackPlugin())
-  import { Scrim, useStack } from '@vuetify/v0'
-  import { computed, onScopeDispose, shallowRef, watch } from 'vue'
+  import { createStack, Scrim } from '@vuetify/v0'
+  import { computed, onScopeDispose, provide, shallowRef, watch } from 'vue'
   import { provideOverlays } from './context'
   import type { Overlay } from './context'
 
-  const stack = useStack()
+  // Create isolated stack for this example (doesn't interfere with app's global stack)
+  const stack = createStack()
+  provide('v0:stack', stack)
 
   // Block body scroll when overlays are active
   watch(() => stack.isActive.value, active => {

apps/docs/src/layouts/default.vue

@@ -1,19 +1,17 @@
 <script setup lang="ts">
   // Framework
-  import { useBreakpoints } from '@vuetify/v0'
+  import { IN_BROWSER, Scrim, useBreakpoints, useStack } from '@vuetify/v0'
 
   // Composables
   import { useAsk } from '@/composables/useAsk'
   import { useDiscovery } from '@/composables/useDiscovery'
   import { createLevelFilter } from '@/composables/useLevelFilter'
   import { createNavConfig } from '@/composables/useNavConfig'
-  import { useNavigation } from '@/composables/useNavigation'
-  import { useScrollLock } from '@/composables/useScrollLock'
   import { useSearch } from '@/composables/useSearch'
   import { useSettings } from '@/composables/useSettings'
 
   // Utilities
-  import { computed, defineAsyncComponent, toRef, watch } from 'vue'
+  import { computed, defineAsyncComponent, onScopeDispose, toRef, watch } from 'vue'
 
   // Stores
   import { useAppStore } from '@/stores/app'
@@ -33,16 +31,15 @@
   const breakpoints = useBreakpoints()
   const discovery = useDiscovery()
   const ask = useAsk()
-  const navigation = useNavigation()
   const search = useSearch()
   const settings = useSettings()
+  const stack = useStack()
 
   // Force reduced motion during tours so elements don't animate
   watch(() => discovery.isActive.value, active => {
     settings.forceReducedMotion.value = active
   })
 
-  const fadeTransition = toRef(() => settings.prefersReducedMotion.value ? undefined : 'fade')
   const slideTransition = toRef(() => settings.prefersReducedMotion.value ? undefined : 'slide')
 
   const isModalOpen = computed(() => {
@@ -52,10 +49,16 @@
     return false
   })
 
-  const isMobileNavOpen = toRef(() => navigation.isOpen.value && !breakpoints.mdAndUp.value)
+  // Unified scroll lock via stack
+  watch(() => stack.isActive.value, active => {
+    if (!IN_BROWSER) return
+    document.body.style.overflow = active ? 'hidden' : ''
+  }, { immediate: true })
 
-  useScrollLock(settings.isOpen)
-  useScrollLock(isMobileNavOpen)
+  onScopeDispose(() => {
+    if (!IN_BROWSER) return
+    document.body.style.overflow = ''
+  })
 </script>
 
 <template>
@@ -79,23 +82,8 @@
 
     <DocsSearch />
 
-    <!-- Mobile nav backdrop -->
-    <Transition :name="fadeTransition">
-      <div
-        v-if="isMobileNavOpen"
-        class="fixed inset-0 bg-black/30 z-9"
-        @click="navigation.close()"
-      />
-    </Transition>
-
-    <!-- Settings backdrop -->
-    <Transition :name="fadeTransition">
-      <div
-        v-if="settings.isOpen.value"
-        class="fixed inset-0 bg-black/30 z-40"
-        @click="settings.close"
-      />
-    </Transition>
+    <!-- Unified scrim for all overlays (teleport disabled to share stacking context) -->
+    <Scrim class="fixed inset-0 bg-black/30 transition-opacity" :teleport="false" />
 
     <!-- Settings sheet -->
     <Transition :name="slideTransition">

apps/docs/src/pages/components/providers/scrim.md

@@ -121,17 +121,20 @@ By default, Scrim teleports to `body`. Disable teleport for inline rendering:
 
 ## Custom Stack Context
 
-For isolated overlay systems, provide a custom stack context:
+For isolated overlay systems, create a custom stack and provide it via Vue's injection system:
 
 ```vue
 <script setup lang="ts">
-  import { Scrim, createStackContext } from '@vuetify/v0'
+  import { provide } from 'vue'
+  import { createStack, Scrim } from '@vuetify/v0'
 
-  const customStack = createStackContext()
+  // Create isolated stack (doesn't interfere with global stack)
+  const stack = createStack()
+  provide('v0:stack', stack)
 </script>
 
 <template>
-  <Scrim :stack="customStack" class="fixed inset-0 bg-black/50" />
+  <Scrim class="fixed inset-0 bg-black/50" />
 </template>
 ```