fix(Drawer): address CodeRabbit review on #2591

Critical:
- DrawerContent.vue: non-modal close-auto-focus and interact-outside
  handlers were reading/writing bare ref variables in template inline
  handlers. Move them to named functions in <script setup> so the
  hasInteractedOutside / hasPointerDownOutside refs are accessed via
  .value explicitly. Fixes broken focus restoration in non-modal mode.
- useSwipeDismiss.ts: preventDefault was guarded on isSwiping.value
  BEFORE processMove, so the very move that crosses the swipe threshold
  (and sets isSwiping=true) was not prevented, causing a one-frame
  scroll hitch on mobile. Capture wasSwiping before processMove and
  prevent on either side of the transition.

Major:
- useSwipeDismiss.ts: the pendingSwipe block was promoting to an active
  swipe even when dir === undefined (user dragging against the dismiss
  direction), which could steal scroll/drag on one-direction drawers.
  Bail out early when no allowed direction is identified.
- DrawerOverlayImpl.vue: useBodyScrollLock was locking unconditionally,
  which could keep page scroll blocked while forceMount kept the overlay
  mounted with the drawer closed. Use the returned `locked` ref and sync
  it with rootContext.open.value via a watcher.
- DrawerRoot.vue: update:openComplete was firing via queueMicrotask,
  which completes almost immediately after the open state changes --
  well before any CSS transition finishes. Move the emit to
  DrawerContentImpl which attaches a one-shot transitionend/animationend
  listener on the popup element and calls rootContext.notifyOpenComplete
  only when the transition actually finishes. Guards against child
  element transitions via event.target === el.
- DrawerSwipeArea.vue: directions array captured the initial value
  only. Wrap in computed so prop/state changes propagate to
  useSwipeDismiss.
- DrawerViewport.vue: only :as and :as-child were forwarded to
  Primitive, dropping class/style/id/listeners/data-attrs. Use
  v-bind="props" to match sibling components.

Minor:
- DrawerIndent.vue: the data-inactive attribute was always set when
  providerContext was missing. Only set when active is explicitly
  false.
- DrawerTrigger.vue: triggerElement was assigned in onMounted only.
  Replace with watch on currentElement so v-if / conditional
  rendering scenarios keep the trigger reference in sync. Clear on
  unmount.
- docs/superpowers/specs/2026-04-04-drawer-design.md: add language
  tags to fenced blocks (text) to satisfy markdownlint MD040.

Not applied:
- story --drawer-snap-height -> --drawer-height: CodeRabbit claimed
  the snap-height var is not produced by the primitive, but it is
  written by DrawerContentImpl:77 when a snap point is active (and
  cleared on 81). Changing the story would break snap-point height
  behavior.

Tests: 32/32 still passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: zernonia

docs/superpowers/specs/2026-04-04-drawer-design.md

@@ -16,7 +16,7 @@ Port the [BaseUI Drawer](https://base-ui.com/react/components/drawer) component
 
 ## Component Structure
 
-```
+```text
 packages/core/src/Drawer/
 ├── DrawerRoot.vue              # Context provider + open/modal/swipeDirection state
 ├── DrawerTrigger.vue           # Primitive button that opens drawer
@@ -209,7 +209,7 @@ When dragging past the fully-open position (overshoot in wrong direction), appli
 
 ### Returns
 
-```
+```text
 {
   swipePointerProps: { onPointerDown, onPointerMove, onPointerUp }
   swipeTouchProps: { onTouchStart, onTouchMove, onTouchEnd }

packages/core/src/Drawer/DrawerContent.vue

@@ -32,6 +32,31 @@ const isTrapFocusOnly = computed(() => rootContext.modal.value === 'trap-focus')
 const shouldTrapFocus = computed(() => (isFullModal.value || isTrapFocusOnly.value) && rootContext.open.value)
 const shouldHideOthers = computed(() => isFullModal.value ? currentElement.value : undefined)
 useHideOthers(shouldHideOthers)
+
+// Non-modal handlers defined as named functions so the refs are accessed via
+// `.value` explicitly and the reads/writes are unambiguous.
+function onCloseAutoFocusNonModal(e: Event) {
+  if (!e.defaultPrevented) {
+    if (!hasInteractedOutside.value)
+      rootContext.triggerElement.value?.focus()
+    e.preventDefault()
+  }
+  hasInteractedOutside.value = false
+  hasPointerDownOutside.value = false
+}
+
+function onInteractOutsideNonModal(e: any) {
+  if (!e.defaultPrevented) {
+    hasInteractedOutside.value = true
+    if (e.detail.originalEvent.type === 'pointerdown')
+      hasPointerDownOutside.value = true
+  }
+  const target = e.target as HTMLElement
+  if (rootContext.triggerElement.value?.contains(target))
+    e.preventDefault()
+  if (e.detail.originalEvent.type === 'focusin' && hasPointerDownOutside.value)
+    e.preventDefault()
+}
 </script>
 
 <template>
@@ -64,24 +89,8 @@ useHideOthers(shouldHideOthers)
       v-bind="{ ...props, ...emitsAsProps, ...$attrs }"
       :trap-focus="shouldTrapFocus"
       :disable-outside-pointer-events="false"
-      @close-auto-focus="(e: Event) => {
-        if (!e.defaultPrevented) {
-          if (!hasInteractedOutside) rootContext.triggerElement.value?.focus()
-          e.preventDefault()
-        }
-        hasInteractedOutside = false
-        hasPointerDownOutside = false
-      }"
-      @interact-outside="(e: any) => {
-        if (!e.defaultPrevented) {
-          hasInteractedOutside = true
-          if (e.detail.originalEvent.type === 'pointerdown')
-            hasPointerDownOutside = true
-        }
-        const target = e.target as HTMLElement
-        if (rootContext.triggerElement.value?.contains(target)) e.preventDefault()
-        if (e.detail.originalEvent.type === 'focusin' && hasPointerDownOutside) e.preventDefault()
-      }"
+      @close-auto-focus="onCloseAutoFocusNonModal"
+      @interact-outside="onInteractOutsideNonModal"
     >
       <slot />
     </DrawerContentImpl>

packages/core/src/Drawer/DrawerContentImpl.vue

@@ -219,6 +219,42 @@ function onInteractOutside(event: any) {
   emits('interactOutside', event)
 }
 
+// --- update:openComplete wiring ---
+// Fire `update:openComplete` on the popup's own transitionend/animationend,
+// not on a microtask — consumers rely on this marker to know the enter/exit
+// transition has actually finished. We track the current listener so a rapid
+// open→close doesn't leak or double-fire, and guard with `event.target === el`
+// so child element transitions don't spuriously resolve the drawer lifecycle.
+let openCompleteCleanup: (() => void) | undefined
+
+function clearOpenCompleteListener() {
+  openCompleteCleanup?.()
+  openCompleteCleanup = undefined
+}
+
+watch(() => rootContext.open.value, (isOpen) => {
+  clearOpenCompleteListener()
+  const el = currentElement.value
+  if (!el) {
+    // If there's no element (e.g. closed without ever mounting), fire
+    // synchronously so consumers still get the contract.
+    rootContext.notifyOpenComplete(isOpen)
+    return
+  }
+  const handler = (event: Event) => {
+    if (event.target !== el)
+      return
+    clearOpenCompleteListener()
+    rootContext.notifyOpenComplete(isOpen)
+  }
+  el.addEventListener('transitionend', handler)
+  el.addEventListener('animationend', handler)
+  openCompleteCleanup = () => {
+    el.removeEventListener('transitionend', handler)
+    el.removeEventListener('animationend', handler)
+  }
+})
+
 // Data attributes
 const dataAttributes = computed(() => {
   const attrs: Record<string, string | undefined> = {
@@ -264,6 +300,7 @@ onMounted(() => {
 onUnmounted(() => {
   rootContext.notifyParentHasNestedDrawer?.(false)
   unsubscribeNestedProgress?.()
+  clearOpenCompleteListener()
 })
 
 // Dev warning for missing DrawerTitle

packages/core/src/Drawer/DrawerIndent.vue

@@ -53,7 +53,7 @@ onUnmounted(() => {
     v-bind="props"
     :ref="forwardRef"
     :data-active="providerContext?.active.value ? '' : undefined"
-    :data-inactive="!providerContext?.active.value ? '' : undefined"
+    :data-inactive="providerContext?.active.value === false ? '' : undefined"
     :style="{ [DRAWER_CSS_VARS.swipeProgress]: '0' }"
   >
     <slot />

packages/core/src/Drawer/DrawerOverlayImpl.vue

@@ -5,7 +5,7 @@ export interface DrawerOverlayImplProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { computed } from 'vue'
+import { computed, watch } from 'vue'
 import { Primitive } from '@/Primitive'
 import { useBodyScrollLock, useForwardExpose } from '@/shared'
 import { injectDrawerRootContext } from './DrawerRoot.vue'
@@ -14,7 +14,14 @@ import { DRAWER_CSS_VARS } from './utils'
 defineProps<DrawerOverlayImplProps>()
 const rootContext = injectDrawerRootContext()
 
-useBodyScrollLock(true)
+// Only lock body scroll while the drawer is actually open. With `forceMount`,
+// the overlay may stay mounted while closed — unconditional lock would keep
+// the page scroll blocked.
+const locked = useBodyScrollLock(rootContext.open.value)
+watch(() => rootContext.open.value, (open) => {
+  locked.value = open
+}, { immediate: true })
+
 useForwardExpose()
 
 // BaseUI parity: the backdrop carries data-swiping / data-swipe-direction so

packages/core/src/Drawer/DrawerRoot.vue

@@ -69,6 +69,7 @@ export interface DrawerRootContext {
   isSwiping: Ref<boolean>
   nestedSwipeProgressStore: NestedSwipeProgressStore
   onOpenChange: (value: boolean, reason?: DrawerOpenChangeReason) => void
+  notifyOpenComplete: (value: boolean) => void
   setActiveSnapPoint: (point: DrawerSnapPoint | null) => void
   onPopupHeightChange: (height: number) => void
   onNestedFrontmostHeightChange: (height: number) => void
@@ -169,6 +170,9 @@ provideDrawerRootContext({
     uncontrolledOpen.value = value
     emit('update:open', value, details)
   },
+  notifyOpenComplete(value) {
+    emit('update:openComplete', value)
+  },
   setActiveSnapPoint(point) { activeSnapPoint.value = point },
   onPopupHeightChange(h) {
     popupHeight.value = h
@@ -223,11 +227,9 @@ watch(open, (isOpen) => {
   }
 }, { immediate: true })
 
-// Emit openComplete after next tick (approximates Base UI's onOpenChangeComplete
-// which fires after CSS transitions. Consumers can refine via onTransitionEnd.)
-watch(open, (isOpen) => {
-  queueMicrotask(() => emit('update:openComplete', isOpen))
-})
+// `update:openComplete` is emitted by DrawerContentImpl after the popup's
+// enter/exit transition actually finishes (via transitionend/animationend on
+// the popup element). DrawerRoot just exposes the notify hook through context.
 
 onUnmounted(() => {
   providerContext?.removeDrawer(contentId)

packages/core/src/Drawer/DrawerSwipeArea.vue

@@ -40,10 +40,14 @@ const openDirection = computed<SwipeDirection>(() => {
 
 const enabled = computed(() => !props.disabled && !rootContext.open.value)
 
+// Keep the directions array reactive — `[openDirection.value]` would capture
+// the initial value only and ignore prop/state updates.
+const directions = computed<SwipeDirection[]>(() => [openDirection.value])
+
 useSwipeDismiss({
   enabled,
   elementRef: currentElement,
-  directions: [openDirection.value],
+  directions,
   movementCssVars: {
     x: DRAWER_CSS_VARS.swipeMovementX,
     y: DRAWER_CSS_VARS.swipeMovementY,

packages/core/src/Drawer/DrawerTrigger.vue

@@ -5,7 +5,7 @@ export interface DrawerTriggerProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { onMounted } from 'vue'
+import { onUnmounted, watch } from 'vue'
 import { Primitive } from '@/Primitive'
 import { useForwardExpose } from '@/shared'
 import { injectDrawerRootContext } from './DrawerRoot.vue'
@@ -14,8 +14,17 @@ const props = withDefaults(defineProps<DrawerTriggerProps>(), { as: 'button' })
 const rootContext = injectDrawerRootContext()
 const { forwardRef, currentElement } = useForwardExpose()
 
-onMounted(() => {
-  rootContext.triggerElement.value = currentElement.value
+// Keep triggerElement in sync with the rendered element — useForwardExpose's
+// currentElement is a reactive computed ref, and v-if / conditional rendering
+// can swap the underlying DOM node, so a one-shot onMounted assignment would
+// go stale and break finalFocus restoration in DrawerContent.
+watch(currentElement, (el) => {
+  rootContext.triggerElement.value = el
+}, { immediate: true })
+
+onUnmounted(() => {
+  if (rootContext.triggerElement.value === currentElement.value)
+    rootContext.triggerElement.value = undefined
 })
 </script>
 

packages/core/src/Drawer/DrawerViewport.vue

@@ -17,16 +17,15 @@ import { injectDrawerRootContext } from './DrawerRoot.vue'
  * this component is currently a passthrough that carries the `data-drawer-viewport`
  * attribute for downstream selectors. It exists primarily for API parity.
  */
-withDefaults(defineProps<DrawerViewportProps>(), { as: 'div' })
+const props = withDefaults(defineProps<DrawerViewportProps>(), { as: 'div' })
 const { forwardRef } = useForwardExpose()
 const rootContext = injectDrawerRootContext()
 </script>
 
 <template>
   <Primitive
+    v-bind="props"
     :ref="forwardRef"
-    :as="as"
-    :as-child="asChild"
     data-drawer-viewport=""
     :data-state="rootContext.open.value ? 'open' : 'closed'"
   >

packages/core/src/Drawer/composables/useSwipeDismiss.ts

@@ -263,8 +263,14 @@ export function useSwipeDismiss(options: UseSwipeDismissOptions) {
     const dir: SwipeDirection | undefined = toValue(directions).find(d => getDisplacement(d, dx, dy) > 0)
 
     if (pendingSwipe && pendingSwipeStartPos) {
+      // Only promote to an active swipe when we've identified an allowed
+      // direction. If the user is dragging against the dismiss direction
+      // (dir === undefined), bail out so we don't steal scroll/drag from
+      // one-direction drawers.
+      if (!dir)
+        return
       const pending = getDisplacement(
-        dir ?? toValue(directions)[0],
+        dir,
         pos.x - pendingSwipeStartPos.x,
         pos.y - pendingSwipeStartPos.y,
       )
@@ -481,10 +487,14 @@ export function useSwipeDismiss(options: UseSwipeDismissOptions) {
       // will lock the axis and retry the decision on the next frame.
     }
 
-    if (isSwiping.value)
-      e.preventDefault()
-
+    // Capture swiping state BEFORE processMove — that function is what sets
+    // isSwiping.value = true on the move that crosses the drag threshold, so
+    // we need to preventDefault on that same event (not the next one) to avoid
+    // a visible scroll hitch on the first frame of the gesture on mobile.
+    const wasSwiping = isSwiping.value
     processMove(el, pos, e.timeStamp)
+    if (wasSwiping || isSwiping.value)
+      e.preventDefault()
   }
 
   function onTouchEnd() {