@tamagui/sheet 2.0.0-1769546410712 → 2.0.0-1769550075301

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamagui/sheet",
-  "version": "2.0.0-1769546410712",
+  "version": "2.0.0-1769550075301",
   "type": "module",
   "sideEffects": [
     "*.css"
@@ -72,24 +72,24 @@
     }
   },
   "dependencies": {
-    "@tamagui/adapt": "2.0.0-1769546410712",
-    "@tamagui/animate-presence": "2.0.0-1769546410712",
-    "@tamagui/animations-react-native": "2.0.0-1769546410712",
-    "@tamagui/compose-refs": "2.0.0-1769546410712",
-    "@tamagui/constants": "2.0.0-1769546410712",
-    "@tamagui/core": "2.0.0-1769546410712",
-    "@tamagui/create-context": "2.0.0-1769546410712",
-    "@tamagui/helpers": "2.0.0-1769546410712",
-    "@tamagui/native": "2.0.0-1769546410712",
-    "@tamagui/portal": "2.0.0-1769546410712",
-    "@tamagui/remove-scroll": "2.0.0-1769546410712",
-    "@tamagui/scroll-view": "2.0.0-1769546410712",
-    "@tamagui/stacks": "2.0.0-1769546410712",
-    "@tamagui/use-constant": "2.0.0-1769546410712",
-    "@tamagui/use-controllable-state": "2.0.0-1769546410712",
-    "@tamagui/use-did-finish-ssr": "2.0.0-1769546410712",
-    "@tamagui/use-keyboard-visible": "2.0.0-1769546410712",
-    "@tamagui/z-index-stack": "2.0.0-1769546410712"
+    "@tamagui/adapt": "2.0.0-1769550075301",
+    "@tamagui/animate-presence": "2.0.0-1769550075301",
+    "@tamagui/animations-react-native": "2.0.0-1769550075301",
+    "@tamagui/compose-refs": "2.0.0-1769550075301",
+    "@tamagui/constants": "2.0.0-1769550075301",
+    "@tamagui/core": "2.0.0-1769550075301",
+    "@tamagui/create-context": "2.0.0-1769550075301",
+    "@tamagui/helpers": "2.0.0-1769550075301",
+    "@tamagui/native": "2.0.0-1769550075301",
+    "@tamagui/portal": "2.0.0-1769550075301",
+    "@tamagui/remove-scroll": "2.0.0-1769550075301",
+    "@tamagui/scroll-view": "2.0.0-1769550075301",
+    "@tamagui/stacks": "2.0.0-1769550075301",
+    "@tamagui/use-constant": "2.0.0-1769550075301",
+    "@tamagui/use-controllable-state": "2.0.0-1769550075301",
+    "@tamagui/use-did-finish-ssr": "2.0.0-1769550075301",
+    "@tamagui/use-keyboard-visible": "2.0.0-1769550075301",
+    "@tamagui/z-index-stack": "2.0.0-1769550075301"
   },
   "peerDependencies": {
     "react": "*",
@@ -102,7 +102,7 @@
     }
   },
   "devDependencies": {
-    "@tamagui/build": "2.0.0-1769546410712",
+    "@tamagui/build": "2.0.0-1769550075301",
     "react": "*",
     "react-native": "0.81.5",
     "react-native-gesture-handler": "~2.28.0"

package/src/SheetImplementationCustom.tsx

@@ -19,19 +19,41 @@ import type {
   LayoutChangeEvent,
   PanResponderGestureState,
 } from 'react-native'
-import { Dimensions, Keyboard, PanResponder, View } from 'react-native'
+import { Dimensions, PanResponder, View } from 'react-native'
 import { ParentSheetContext, SheetInsideSheetContext } from './contexts'
 import { GestureDetectorWrapper } from './GestureDetectorWrapper'
 import { GestureSheetProvider } from './GestureSheetContext'
+import { getSafeArea } from '@tamagui/native'
 import { resisted } from './helpers'
 import { SheetProvider } from './SheetContext'
 import type { SheetProps, SnapPointsMode } from './types'
 import { useGestureHandlerPan } from './useGestureHandlerPan'
+import { useKeyboardControllerSheet } from './useKeyboardControllerSheet'
 import { useSheetOpenState } from './useSheetOpenState'
 import { useSheetProviderProps } from './useSheetProviderProps'
 
 const hiddenSize = 10_000.1
 
+// safe area top inset, cached per-session (device-constant value)
+let _cachedSafeAreaTop: number | undefined
+function getSafeAreaTopInset(): number {
+  if (_cachedSafeAreaTop !== undefined) return _cachedSafeAreaTop
+  // try tamagui native safe area state first
+  const sa = getSafeArea()
+  if (sa.isEnabled) {
+    _cachedSafeAreaTop = sa.getInsets().top
+    return _cachedSafeAreaTop
+  }
+  // fallback: react-native-safe-area-context initialWindowMetrics (no provider needed)
+  try {
+    const sac = require('react-native-safe-area-context')
+    _cachedSafeAreaTop = sac.initialWindowMetrics?.insets?.top ?? 0
+  } catch {
+    _cachedSafeAreaTop = 0
+  }
+  return _cachedSafeAreaTop ?? 0
+}
+
 let sheetHiddenStyleSheet: HTMLStyleElement | null = null
 
 // on web we are always relative to window, on to screen
@@ -141,6 +163,74 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       [screenSize, effectiveFrameSize, snapPoints, snapPointsMode]
     )
 
+    // keyboard state tracking — just tracks height/visibility, no position animation.
+    // Position animation is handled via keyboard-adjusted positions below,
+    // matching the react-native-actions-sheet pattern.
+    const {
+      keyboardHeight,
+      isKeyboardVisible,
+      dismissKeyboard,
+      pauseKeyboardHandler,
+      flushPendingHide,
+    } = useKeyboardControllerSheet({
+      enabled: !isWeb && Boolean(moveOnKeyboardChange),
+    })
+
+    const [isDragging, setIsDragging_] = React.useState(false)
+
+    // synchronous dragging ref — set BEFORE async state commits.
+    // RNGH onBegin fires before keyboard hide event reaches JS,
+    // so the ref is true by the time activePositions memo re-evaluates.
+    // Also controls pauseKeyboardHandler to freeze keyboard state during drag.
+    const isDraggingRef = React.useRef(false)
+    const setIsDragging = React.useCallback(
+      (val: boolean) => {
+        isDraggingRef.current = val
+        pauseKeyboardHandler.current = val
+        setIsDragging_(val)
+        // when drag ends, flush any keyboard hide that was suppressed during drag
+        // so isKeyboardVisible/keyboardHeight reflect actual state
+        if (!val) {
+          flushPendingHide()
+        }
+      },
+      [pauseKeyboardHandler, flushPendingHide]
+    )
+
+    // keyboard-adjusted positions: shift snap points up by keyboard height
+    // when keyboard is visible. This drives both gesture snap calculation
+    // and animation targets — keyboard never dismissed during drag.
+    // Capped at safe area top inset so the sheet never goes above the notch/status bar
+    // (matching the react-native-actions-sheet pattern).
+    //
+    // IMPORTANT: frozen during drag to prevent gesture handler recreation.
+    // When user drags, TextInput may blur → keyboard dismisses → positions would revert,
+    // causing the gesture useMemo to recreate and cancel the active drag.
+    // The post-drag reconciliation effect handles animating to correct position after drag ends.
+    const activePositionsRef = React.useRef(positions)
+    const activePositions = React.useMemo(() => {
+      // during drag, return frozen positions to prevent gesture handler recreation.
+      // check both state (for re-render trigger) and ref (for synchronous check
+      // when keyboard hide event fires before isDragging state commits)
+      if (isDragging || isDraggingRef.current) return activePositionsRef.current
+
+      let result: number[]
+      if (!isKeyboardVisible || keyboardHeight <= 0) {
+        result = positions
+      } else {
+        const safeAreaTop = isWeb ? 0 : getSafeAreaTopInset()
+        result = positions.map((p) => {
+          // don't adjust the off-screen/close position (from dismissOnSnapToBottom's 0% snap)
+          // — it must stay at screenSize so the user can drag between real snap points
+          // without accidentally closing the sheet
+          if (screenSize && p >= screenSize) return p
+          return Math.max(safeAreaTop, p - keyboardHeight)
+        })
+      }
+      activePositionsRef.current = result
+      return result
+    }, [positions, isKeyboardVisible, keyboardHeight, screenSize, isDragging])
+
     const { useAnimatedNumber, useAnimatedNumberStyle, useAnimatedNumberReaction } =
       animationDriver
     const AnimatedView = (animationDriver.View ?? TamaguiView) as typeof Animated.View
@@ -179,8 +269,8 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
           at.current = value
           scrollBridge.paneY = value
           // update isAtTop for scroll enable/disable
-          // positions[0] is the top snap point (minY)
-          const minY = positions[0]
+          // activePositions[0] is the top snap point (keyboard-adjusted minY)
+          const minY = activePositions[0]
           const wasAtTop = scrollBridge.isAtTop
           const nowAtTop = value <= minY + 5
           if (wasAtTop !== nowAtTop) {
@@ -196,7 +286,7 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
             }
           }
         },
-        [animationDriver, positions]
+        [animationDriver, activePositions]
       )
     )
 
@@ -208,20 +298,23 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       }
     }
 
-    const animateTo = useEvent((position: number) => {
+    const animateTo = useEvent((position: number, animationOverride?: any) => {
       if (frameSize === 0) return
 
-      let toValue = isHidden || position === -1 ? screenSize : positions[position]
+      let toValue = isHidden || position === -1 ? screenSize : activePositions[position]
 
       if (at.current === toValue) return
 
       at.current = toValue
       stopSpring()
 
-      animatedNumber.setValue(toValue, {
-        type: 'spring',
-        ...transitionConfig,
-      })
+      animatedNumber.setValue(
+        toValue,
+        animationOverride || {
+          type: 'spring',
+          ...transitionConfig,
+        }
+      )
     })
 
     useIsomorphicLayoutEffect(() => {
@@ -282,7 +375,6 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
 
     const disableDrag = props.disableDrag ?? controller?.disableDrag
     const themeName = useThemeName()
-    const [isDragging, setIsDragging] = React.useState(false)
     const [blockPan, setBlockPan] = React.useState(false)
 
     const panResponder = React.useMemo(() => {
@@ -442,9 +534,41 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       })
     }, [disableDrag, isShowingInnerSheet, animateTo, frameSize, positions, setPosition])
 
+    // animate to keyboard-adjusted position when keyboard state changes
+    React.useEffect(() => {
+      if (isDragging || isHidden || !open || disableAnimation) return
+      if (!frameSize || !screenSize) return
+      // use timing animation to match iOS keyboard animation (~250ms)
+      animateTo(position, { type: 'timing', duration: 250 })
+    }, [isKeyboardVisible, keyboardHeight])
+
+    // reconcile position after drag ends — if keyboard dismissed during drag
+    // (e.g., input blur), activePositions reverted but onEnd used frozen positions
+    // for snap index. This effect ensures the sheet animates to the correct
+    // non-keyboard-adjusted position for the chosen snap index.
+    const wasDragging = React.useRef(false)
+    React.useEffect(() => {
+      if (isDragging) {
+        wasDragging.current = true
+        return
+      }
+      if (!wasDragging.current) return
+      wasDragging.current = false
+      // drag just ended — reconcile position with latest activePositions
+      if (!frameSize || !screenSize || isHidden || !open) return
+      animateTo(position)
+    }, [isDragging])
+
+    // dismiss keyboard when sheet closes
+    React.useEffect(() => {
+      if (!open && isKeyboardVisible) {
+        dismissKeyboard()
+      }
+    }, [open])
+
     // gesture handler hook for RNGH-based gesture coordination
     const { panGesture, panGestureRef, gestureHandlerEnabled } = useGestureHandlerPan({
-      positions,
+      positions: activePositions,
       frameSize,
       setPosition,
       animateTo,
@@ -457,9 +581,10 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       isShowingInnerSheet,
       setAnimatedPosition: (val: number) => {
         // directly set the animated value for smooth dragging
-        // console.warn('[RNGH-Sheet] setAnimatedPosition:', val.toFixed(1))
+        at.current = val
         animatedNumber.setValue(val, { type: 'direct' })
       },
+      pauseKeyboardHandler,
     })
 
     const handleAnimationViewLayout = React.useCallback(
@@ -500,39 +625,6 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       }
     })
 
-    const sizeBeforeKeyboard = React.useRef<number | null>(null)
-    React.useEffect(() => {
-      if (isWeb || !moveOnKeyboardChange) return
-      const keyboardShowListener = Keyboard.addListener(
-        currentPlatform === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow',
-        (e) => {
-          if (sizeBeforeKeyboard.current !== null) return
-          sizeBeforeKeyboard.current =
-            isHidden || position === -1 ? screenSize : positions[position]
-          animatedNumber.setValue(
-            Math.max(sizeBeforeKeyboard.current - e.endCoordinates.height, 0),
-            {
-              type: 'timing',
-              duration: 250,
-            }
-          )
-        }
-      )
-      const keyboardDidHideListener = Keyboard.addListener('keyboardDidHide', () => {
-        if (sizeBeforeKeyboard.current === null) return
-        animatedNumber.setValue(sizeBeforeKeyboard.current, {
-          type: 'timing',
-          duration: 250,
-        })
-        sizeBeforeKeyboard.current = null
-      })
-
-      return () => {
-        keyboardDidHideListener.remove()
-        keyboardShowListener.remove()
-      }
-    }, [moveOnKeyboardChange, positions, position, isHidden])
-
     // we need to set this *after* fully closed to 0, to avoid it overlapping
     // the page when resizing quickly on web for example
     const [opacity, setOpacity] = React.useState(open ? 1 : 0)

package/src/SheetScrollView.tsx

@@ -279,6 +279,8 @@ export const SheetScrollView = React.forwardRef<
           }}
           contentContainerStyle={{ minHeight: '100%' }}
           bounces={false}
+          keyboardShouldPersistTaps="always"
+          keyboardDismissMode="none"
           {...props}
         >
           {/* wrapper to measure actual content height (not min-height expanded) */}

package/src/types.tsx

@@ -125,3 +125,50 @@ export type ScrollBridge = {
   // whether sheet is at top position (for scroll enable/disable)
   isAtTop?: boolean
 }
+
+// keyboard controller sheet types
+
+export interface KeyboardControllerSheetOptions {
+  /**
+   * Whether keyboard handling is enabled.
+   * When false, the hook is a no-op.
+   */
+  enabled: boolean
+}
+
+export interface KeyboardControllerSheetResult {
+  /**
+   * Whether keyboard-controller is available and enabled.
+   */
+  keyboardControllerEnabled: boolean
+
+  /**
+   * Current keyboard height (0 when hidden).
+   * On web or when keyboard-controller is not available, always 0.
+   */
+  keyboardHeight: number
+
+  /**
+   * Whether the keyboard is currently visible.
+   */
+  isKeyboardVisible: boolean
+
+  /**
+   * Dismiss the keyboard programmatically.
+   * Called when sheet closes to dismiss the keyboard.
+   */
+  dismissKeyboard: () => void
+
+  /**
+   * Ref to pause keyboard hide state updates (action-sheet pattern).
+   * When true, keyboard hide events are ignored — keeps isKeyboardVisible=true
+   * and keyboardHeight at their last values during drag.
+   */
+  pauseKeyboardHandler: React.RefObject<boolean>
+
+  /**
+   * Flush any keyboard hide event that was suppressed while paused.
+   * Call after drag ends to reconcile actual keyboard state.
+   */
+  flushPendingHide: () => void
+}

package/src/useGestureHandlerPan.tsx

@@ -10,7 +10,7 @@ interface GesturePanConfig {
   positions: number[]
   frameSize: number
   setPosition: (pos: number) => void
-  animateTo: (pos: number) => void
+  animateTo: (pos: number, animationOverride?: any) => void
   stopSpring: () => void
   scrollBridge: ScrollBridge
   setIsDragging: (val: boolean) => void
@@ -22,6 +22,8 @@ interface GesturePanConfig {
   setAnimatedPosition: (val: number) => void
   // ref to scroll gesture for simultaneousWithExternalGesture
   scrollGestureRef?: RefObject<any> | null
+  // ref to pause keyboard hide events during gesture (action-sheet pattern)
+  pauseKeyboardHandler?: RefObject<boolean>
 }
 
 interface GesturePanResult {
@@ -80,21 +82,26 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
     prevTranslationY: 0,
     // track if scroll was engaged (scrollY > 0) at some point
     scrollEngaged: false,
+    // positions frozen at gesture start — keyboard may dismiss during drag (input blur),
+    // causing positions to revert. Frozen positions ensure stable snap calculation.
+    frozenPositions: [] as number[],
+    frozenMinY: 0,
+    // whether pan gesture actually started (vs just a tap in onBegin)
+    panStarted: false,
   })
 
   const onStart = useCallback(() => {
     stopSpring()
-    setIsDragging(true)
-  }, [stopSpring, setIsDragging])
+  }, [stopSpring])
 
   const onEnd = useCallback(
-    (closestPoint: number) => {
+    (closestPoint: number, animationOverride?: any) => {
       setIsDragging(false)
       scrollBridge.setParentDragging(false)
       // re-enable scroll when gesture ends
       scrollBridge.setScrollEnabled?.(true)
       setPosition(closestPoint)
-      animateTo(closestPoint)
+      animateTo(closestPoint, animationOverride)
     },
     [setIsDragging, scrollBridge, setPosition, animateTo]
   )
@@ -122,6 +129,18 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
       .failOffsetX([-20, 20])
       .shouldCancelWhenOutside(false)
       .onBegin(() => {
+        // onBegin fires on ANY touch (including taps to focus inputs).
+        // We do NOT set isDragging here — that would block keyboard animation.
+        // Instead, isDragging is set in onStart (actual pan gesture recognized).
+        gs.panStarted = false
+
+        // lightweight: pause keyboard handler to suppress hide events during gesture.
+        // This prevents keyboard flicker if input blurs before onStart.
+        // If this is just a tap, onFinalize un-pauses without setting isDragging.
+        if (config.pauseKeyboardHandler) {
+          config.pauseKeyboardHandler.current = true
+        }
+
         // check position at gesture begin - before direction is known
         const pos = getCurrentPosition()
         const atTop = pos <= minY + AT_TOP_THRESHOLD
@@ -132,6 +151,10 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         gs.accumulatedOffset = 0
         gs.prevTranslationY = 0
         gs.scrollEngaged = currentScrollY > 0 // track if scroll is already engaged
+        // freeze positions at gesture start so keyboard dismiss during drag
+        // doesn't change snap targets mid-gesture
+        gs.frozenPositions = [...positions]
+        gs.frozenMinY = minY
 
         // if sheet not at top, DISABLE SCROLL immediately and lock to 0
         // this prevents scroll from firing before pan takes over
@@ -140,6 +163,11 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         }
       })
       .onStart(() => {
+        // onStart fires only when pan gesture is recognized (finger moved enough).
+        // Safe to set isDragging here — this won't fire for taps to focus inputs.
+        gs.panStarted = true
+        setIsDragging(true)
+
         // console.warn('[RNGH-Pan] onStart', { startY: gs.startY, minY })
         scrollBridge.initialPosition = gs.startY
         onStart()
@@ -250,21 +278,30 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         // clear scroll lock
         scrollBridge.scrollLockY = undefined
 
+        // use frozen positions from gesture start — keyboard may have dismissed
+        // during drag (input blur), reverting activePositions. Frozen positions
+        // ensure the snap index reflects the user's intent at drag start.
+        // The onEnd callback's animateTo uses latest activePositions for the
+        // actual animation target, so the sheet ends up at the right place.
+        const snapPositions =
+          gs.frozenPositions.length > 0 ? gs.frozenPositions : positions
+        const snapMinY = gs.frozenPositions.length > 0 ? gs.frozenMinY : minY
+
         // if sheet is at top and scroll is engaged, just stay at top
-        if (currentPos <= minY + AT_TOP_THRESHOLD && scrollBridge.y > 0) {
+        if (currentPos <= snapMinY + AT_TOP_THRESHOLD && scrollBridge.y > 0) {
           onEnd(0)
           return
         }
 
-        // find closest snap point using current position and velocity
+        // snap calculation using frozen positions
         const velocity = velocityY / 1000
         const projectedEnd = currentPos + frameSize * velocity * 0.2
 
         let closestPoint = 0
         let minDist = Number.POSITIVE_INFINITY
 
-        for (let i = 0; i < positions.length; i++) {
-          const pos = positions[i]
+        for (let i = 0; i < snapPositions.length; i++) {
+          const pos = snapPositions[i]
           const dist = Math.abs(projectedEnd - pos)
           if (dist < minDist) {
             minDist = dist
@@ -275,9 +312,19 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         onEnd(closestPoint)
       })
       .onFinalize(() => {
-        // console.warn('[RNGH-Pan] onFinalize')
+        // console.warn('[RNGH-Pan] onFinalize', { panStarted: gs.panStarted })
         // clear scroll lock on finalize too (safety)
         scrollBridge.scrollLockY = undefined
+        if (gs.panStarted) {
+          // real pan gesture — reset isDragging (also un-pauses keyboard handler + flushes)
+          setIsDragging(false)
+        } else {
+          // just a tap (onBegin fired but onStart never did) — un-pause keyboard handler
+          // without setting isDragging (which would block keyboard animation effect)
+          if (config.pauseKeyboardHandler) {
+            config.pauseKeyboardHandler.current = false
+          }
+        }
       })
       .runOnJS(true)
 

package/src/useKeyboardControllerSheet.native.ts

@@ -0,0 +1,136 @@
+/**
+ * Native implementation of keyboard controller sheet hook.
+ *
+ * Simplified to just track keyboard state (height, visibility).
+ * Position animation is handled by SheetImplementationCustom via
+ * keyboard-adjusted positions — matching the react-native-actions-sheet pattern.
+ *
+ * Uses react-native-keyboard-controller events when available,
+ * falls back to basic Keyboard API otherwise.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { Keyboard, Platform } from 'react-native'
+import type {
+  KeyboardControllerSheetOptions,
+  KeyboardControllerSheetResult,
+} from './types'
+
+// lazy import state accessors
+let isKeyboardControllerEnabled: () => boolean = () => false
+let getKeyboardControllerState: () => any = () => ({})
+
+try {
+  const nativeModule = require('@tamagui/native')
+  isKeyboardControllerEnabled = nativeModule.isKeyboardControllerEnabled
+  getKeyboardControllerState = nativeModule.getKeyboardControllerState
+} catch {
+  // @tamagui/native not available
+}
+
+export function useKeyboardControllerSheet(
+  options: KeyboardControllerSheetOptions
+): KeyboardControllerSheetResult {
+  const { enabled } = options
+
+  const [keyboardHeight, setKeyboardHeight] = useState(0)
+  const [isKeyboardVisible, setIsKeyboardVisible] = useState(false)
+  const keyboardControllerEnabled = isKeyboardControllerEnabled()
+
+  // action-sheet pattern: pause keyboard hide events during drag
+  // when true, keyboard hide events are ignored so isKeyboardVisible stays true
+  // and activePositions don't revert mid-gesture
+  const pauseKeyboardHandler = useRef(false)
+  // tracks if a keyboard hide event was suppressed while paused
+  const pendingHide = useRef(false)
+
+  // dismiss keyboard helper
+  const dismissKeyboard = useCallback(() => {
+    Keyboard.dismiss()
+    if (keyboardControllerEnabled) {
+      try {
+        const { KeyboardController } = getKeyboardControllerState()
+        KeyboardController?.dismiss?.()
+      } catch {
+        // ignore errors from keyboard-controller
+      }
+    }
+  }, [keyboardControllerEnabled])
+
+  // flush any keyboard hide that was suppressed during drag.
+  // called when drag ends to reconcile actual keyboard state.
+  const flushPendingHide = useCallback(() => {
+    if (pendingHide.current) {
+      pendingHide.current = false
+      setIsKeyboardVisible(false)
+      setKeyboardHeight(0)
+    }
+  }, [])
+
+  // keyboard-controller event listeners (preferred when available)
+  useEffect(() => {
+    if (!enabled || !keyboardControllerEnabled) return
+
+    const { KeyboardEvents } = getKeyboardControllerState()
+    if (!KeyboardEvents?.addListener) return
+
+    const showSub = KeyboardEvents.addListener('keyboardWillShow', (e: any) => {
+      const height = e?.height ?? 0
+      if (height > 0) {
+        setKeyboardHeight(height)
+      }
+      setIsKeyboardVisible(true)
+    })
+
+    const hideSub = KeyboardEvents.addListener('keyboardWillHide', () => {
+      if (pauseKeyboardHandler.current) {
+        pendingHide.current = true
+        return
+      }
+      setIsKeyboardVisible(false)
+      setKeyboardHeight(0)
+    })
+
+    return () => {
+      showSub?.remove?.()
+      hideSub?.remove?.()
+    }
+  }, [enabled, keyboardControllerEnabled])
+
+  // fallback to basic Keyboard API when keyboard-controller not available
+  useEffect(() => {
+    if (!enabled) return
+    if (keyboardControllerEnabled) return
+
+    const showEvent = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow'
+    const hideEvent = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide'
+
+    const showListener = Keyboard.addListener(showEvent, (e) => {
+      setKeyboardHeight(e.endCoordinates.height)
+      setIsKeyboardVisible(true)
+    })
+
+    const hideListener = Keyboard.addListener(hideEvent, () => {
+      if (pauseKeyboardHandler.current) {
+        pendingHide.current = true
+        return
+      }
+      setIsKeyboardVisible(false)
+      setKeyboardHeight(0)
+    })
+
+    return () => {
+      showListener.remove()
+      hideListener.remove()
+    }
+  }, [enabled, keyboardControllerEnabled])
+
+  return {
+    keyboardControllerEnabled,
+    keyboardHeight,
+    isKeyboardVisible,
+    dismissKeyboard,
+    pauseKeyboardHandler,
+    flushPendingHide,
+  }
+}