@hanzogui/sheet 2.0.0

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('@hanzogui/native')
+  isKeyboardControllerEnabled = nativeModule.isKeyboardControllerEnabled
+  getKeyboardControllerState = nativeModule.getKeyboardControllerState
+} catch {
+  // @hanzogui/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,
+  }
+}

package/src/useKeyboardControllerSheet.ts

@@ -0,0 +1,26 @@
+/**
+ * Web stub for keyboard controller sheet hook.
+ * Returns no-op values since keyboard-controller is native-only.
+ */
+
+import { useRef } from 'react'
+import type {
+  KeyboardControllerSheetOptions,
+  KeyboardControllerSheetResult,
+} from './types'
+
+const noop = () => {}
+
+export function useKeyboardControllerSheet(
+  _options: KeyboardControllerSheetOptions
+): KeyboardControllerSheetResult {
+  const pauseKeyboardHandler = useRef(false)
+  return {
+    keyboardControllerEnabled: false,
+    keyboardHeight: 0,
+    isKeyboardVisible: false,
+    dismissKeyboard: noop,
+    pauseKeyboardHandler,
+    flushPendingHide: noop,
+  }
+}

package/src/useSheet.tsx

@@ -0,0 +1,3 @@
+import { useSheetContext } from './SheetContext'
+
+export const useSheet = () => useSheetContext('', undefined)

package/src/useSheetController.tsx

@@ -0,0 +1,27 @@
+import React from 'react'
+
+export const useSheetController = () => {
+  const controller = React.useContext(SheetControllerContext)
+  const isHidden = controller?.hidden
+  const isShowingNonSheet = isHidden && controller?.open
+  return {
+    controller,
+    isHidden,
+    isShowingNonSheet,
+    disableDrag: controller?.disableDrag,
+  }
+}
+
+export const SheetControllerContext =
+  React.createContext<SheetControllerContextValue | null>(null)
+
+export type SheetControllerContextValue = {
+  id?: string
+  disableDrag?: boolean
+  open?: boolean
+  // hide without "closing" to prevent re-animation when shown again
+  hidden?: boolean
+  onOpenChange?: React.Dispatch<React.SetStateAction<boolean>> | ((val: boolean) => void)
+  // when true, the sheet should skip its open animation (used for adapt handoff)
+  skipNextAnimation?: boolean
+}

package/src/useSheetOffscreenSize.tsx

@@ -0,0 +1,49 @@
+import type { SheetContextValue } from './useSheetProviderProps'
+
+export const useSheetOffscreenSize = ({
+  snapPoints,
+  position,
+  screenSize,
+  frameSize,
+  snapPointsMode,
+}: SheetContextValue) => {
+  if (snapPointsMode === 'fit') {
+    return 0
+  }
+
+  if (snapPointsMode === 'constant') {
+    const maxSize = Number(snapPoints[0])
+    const currentSize = Number(snapPoints[position] ?? 0)
+    const offscreenSize = maxSize - currentSize
+    return offscreenSize
+  }
+
+  if (snapPointsMode === 'percent') {
+    const maxPercentOpened = Number(snapPoints[0]) / 100
+    const percentOpened = Number(snapPoints[position] ?? 0) / 100
+    const percentHidden = maxPercentOpened - percentOpened
+    const offscreenSize = percentHidden * screenSize
+    return offscreenSize
+  }
+
+  // mixed:
+  const maxSnapPoint = snapPoints[0]
+  if (maxSnapPoint === 'fit') {
+    return 0
+  }
+
+  const maxSize =
+    typeof maxSnapPoint === 'string'
+      ? (Number(maxSnapPoint.slice(0, -1)) / 100) * screenSize
+      : maxSnapPoint
+  const currentSnapPoint = snapPoints[position] ?? 0
+  const currentSize =
+    typeof currentSnapPoint === 'string'
+      ? (Number(currentSnapPoint.slice(0, -1)) / 100) * screenSize
+      : currentSnapPoint
+  const offscreenSize = maxSize - currentSize
+  if (Number.isNaN(offscreenSize)) {
+    return 0
+  }
+  return offscreenSize
+}

package/src/useSheetOpenState.tsx

@@ -0,0 +1,33 @@
+import { useControllableState } from '@hanzogui/use-controllable-state'
+
+import type { SheetProps } from './types'
+import { useSheetController } from './useSheetController'
+
+export const useSheetOpenState = (props: SheetProps) => {
+  const { isHidden, controller } = useSheetController()
+
+  const onOpenChangeInternal = (val: boolean) => {
+    controller?.onOpenChange?.(val)
+    props.onOpenChange?.(val)
+  }
+
+  const propVal = props.preferAdaptParentOpenState
+    ? (controller?.open ?? props.open)
+    : (props.open ?? controller?.open)
+
+  const [open, setOpen] = useControllableState({
+    prop: propVal,
+    defaultProp: props.defaultOpen ?? false,
+    onChange: onOpenChangeInternal,
+    strategy: 'most-recent-wins',
+  })
+
+  return {
+    open,
+    setOpen,
+    isHidden,
+    controller,
+  }
+}
+
+export type SheetOpenState = ReturnType<typeof useSheetOpenState>

package/src/useSheetProviderProps.tsx

@@ -0,0 +1,223 @@
+import React from 'react'
+import type { GuiElement } from '@hanzogui/core'
+import { useConfiguration } from '@hanzogui/core'
+import { useConstant } from '@hanzogui/use-constant'
+import { useControllableState } from '@hanzogui/use-controllable-state'
+
+import type { ScrollBridge, SheetProps } from './types'
+import type { SheetOpenState } from './useSheetOpenState'
+
+export type SheetContextValue = ReturnType<typeof useSheetProviderProps> & {
+  setHasScrollView: (val: boolean) => void
+}
+
+export function useSheetProviderProps(
+  props: SheetProps,
+  state: SheetOpenState,
+  options: {
+    onOverlayComponent?: (comp: any) => void
+  } = {}
+) {
+  const handleRef = React.useRef<GuiElement>(null)
+  const contentRef = React.useRef<GuiElement>(null)
+  const [frameSize, setFrameSize] = React.useState<number>(0)
+  const [maxContentSize, setMaxContentSize] = React.useState<number>(0)
+  const snapPointsMode = props.snapPointsMode ?? 'percent'
+  const snapPointsProp: (string | number)[] =
+    props.snapPoints ??
+    (snapPointsMode === 'percent'
+      ? [80]
+      : snapPointsMode === 'constant'
+        ? [256]
+        : ['fit'])
+  const hasFit = snapPointsProp[0] === 'fit'
+
+  const snapPoints = React.useMemo(
+    () => (props.dismissOnSnapToBottom ? [...snapPointsProp, 0] : snapPointsProp),
+
+    [JSON.stringify(snapPointsProp), props.dismissOnSnapToBottom]
+  )
+
+  // lets set -1 to be always the "open = false" position
+  const [position_, setPositionImmediate] = useControllableState({
+    prop: props.position,
+    defaultProp: props.defaultPosition || (state.open ? 0 : -1),
+    onChange: props.onPositionChange,
+    strategy: 'most-recent-wins',
+  })
+
+  const position = state.open === false ? -1 : position_
+
+  const { open } = state
+
+  const setPosition = React.useCallback(
+    (next: number) => {
+      // close on dismissOnSnapToBottom (and set position so it animates)
+      if (props.dismissOnSnapToBottom && next === snapPoints.length - 1) {
+        state.setOpen(false)
+      } else {
+        setPositionImmediate(next)
+      }
+    },
+    [props.dismissOnSnapToBottom, snapPoints.length, setPositionImmediate, state.setOpen]
+  )
+
+  if (process.env.NODE_ENV === 'development') {
+    if (
+      snapPointsMode === 'mixed' &&
+      snapPoints.some((p) => {
+        if (typeof p === 'string') {
+          if (p === 'fit') {
+            return false
+          }
+          if (p.endsWith('%')) {
+            const n = Number(p.slice(0, -1))
+            return n < 0 || n > 100
+          }
+          return true
+        }
+        return typeof p !== 'number' || p < 0
+      })
+    ) {
+      console.warn(
+        '⚠️ Invalid snapPoint given, snapPoints must be positive numeric values, string percentages between 0-100%, or "fit" when snapPointsMode is mixed'
+      )
+    }
+    if (snapPointsMode === 'mixed' && snapPoints.indexOf('fit') > 0) {
+      console.warn(
+        '⚠️ Invalid snapPoint given, "fit" must be the first/largest snap point when snapPointsMode is mixed'
+      )
+    }
+    if (
+      snapPointsMode === 'fit' &&
+      (snapPoints.length !== (props.dismissOnSnapToBottom ? 2 : 1) ||
+        snapPoints[0] !== 'fit')
+    ) {
+      console.warn(
+        '⚠️ Invalid snapPoint given, there are no snap points when snapPointsMode is fit'
+      )
+    }
+    if (
+      snapPointsMode === 'constant' &&
+      snapPoints.some((p) => typeof p !== 'number' || p < 0)
+    ) {
+      console.warn(
+        '⚠️ Invalid snapPoint given, snapPoints must be positive numeric values when snapPointsMode is constant'
+      )
+    }
+    if (
+      snapPointsMode === 'percent' &&
+      snapPoints.some((p) => typeof p !== 'number' || p < 0 || p > 100)
+    ) {
+      console.warn(
+        '⚠️ Invalid snapPoint given, snapPoints must be numeric values between 0 and 100 when snapPointsMode is percent'
+      )
+    }
+  }
+
+  // reset position to fully open on re-open after dismissOnSnapToBottom
+  if (open && props.dismissOnSnapToBottom && position === snapPoints.length - 1) {
+    setPositionImmediate(0)
+  }
+
+  // open must set position
+  const shouldSetPositionOpen = open && position < 0
+  React.useEffect(() => {
+    if (shouldSetPositionOpen) {
+      setPosition(0)
+    }
+  }, [setPosition, shouldSetPositionOpen])
+
+  const { animationDriver } = useConfiguration()
+  if (!animationDriver) {
+    throw new Error(
+      process.env.NODE_ENV === 'production'
+        ? `❌ 008`
+        : 'Must set animations in gui.config.ts'
+    )
+  }
+
+  const scrollBridge = useConstant<ScrollBridge>(() => {
+    const parentDragListeners = new Set<Function>()
+
+    const bridge: ScrollBridge = {
+      hasScrollableContent: false,
+      enabled: false,
+      y: 0,
+      paneY: 0,
+      paneMinY: 0,
+      scrollStartY: -1,
+      drag: () => {},
+      release: () => {},
+      scrollLock: false,
+      isParentDragging: false,
+      onParentDragging: (cb) => {
+        parentDragListeners.add(cb)
+        return () => {
+          parentDragListeners.delete(cb)
+        }
+      },
+      setParentDragging: (val) => {
+        if (val !== bridge.isParentDragging) {
+          bridge.isParentDragging = val
+          parentDragListeners.forEach((cb) => cb(val))
+        }
+      },
+    }
+
+    return bridge
+  })
+
+  // Handle both new disableRemoveScroll and deprecated forceRemoveScrollEnabled
+  let disableRemoveScroll: boolean | undefined
+  if (props.disableRemoveScroll !== undefined) {
+    // New prop: disableRemoveScroll={true} means RemoveScroll is disabled
+    disableRemoveScroll = props.disableRemoveScroll || !open || !props.modal
+  } else if (props.forceRemoveScrollEnabled !== undefined) {
+    // Deprecated prop: forceRemoveScrollEnabled can override the default
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(
+        '[Sheet] forceRemoveScrollEnabled is deprecated. Use disableRemoveScroll instead.'
+      )
+    }
+    disableRemoveScroll = !props.forceRemoveScrollEnabled
+  } else {
+    // Default: disabled when not open or not modal
+    disableRemoveScroll = !open || !props.modal
+  }
+
+  const maxSnapPoint = snapPoints[0]
+  const screenSize =
+    snapPointsMode === 'percent'
+      ? frameSize / ((typeof maxSnapPoint === 'number' ? maxSnapPoint : 100) / 100)
+      : maxContentSize
+
+  const providerProps = {
+    screenSize,
+    maxSnapPoint,
+    disableRemoveScroll,
+    scrollBridge,
+    modal: !!props.modal,
+    open: state.open,
+    setOpen: state.setOpen,
+    hidden: !!state.isHidden,
+    contentRef,
+    handleRef,
+    frameSize,
+    setFrameSize,
+    dismissOnOverlayPress: props.dismissOnOverlayPress ?? true,
+    dismissOnSnapToBottom: props.dismissOnSnapToBottom ?? false,
+    onOverlayComponent: options.onOverlayComponent,
+    scope: props.__scopeSheet,
+    hasFit,
+    position,
+    snapPoints,
+    snapPointsMode,
+    setMaxContentSize,
+    setPosition,
+    setPositionImmediate,
+    onlyShowFrame: false,
+  }
+
+  return providerProps
+}

package/src/useSheetScrollViewGestures.native.ts

@@ -0,0 +1,163 @@
+import { useRef } from 'react'
+import type { GestureResponderEvent, ScrollView as RNScrollView } from 'react-native'
+import type { ScrollBridge } from './types'
+
+interface ResponderState {
+  lastPageY: number
+  dragAt: number
+  dys: number[]
+  isScrolling: boolean
+  isDraggingScrollArea: boolean
+  scrollEngaged: boolean
+  prevScrollY: number
+  handoffOccurred: boolean
+  handoffDragOffset: number
+}
+
+interface UseSheetScrollViewGesturesProps {
+  scrollRef: React.RefObject<RNScrollView | null>
+  scrollBridge: ScrollBridge
+  hasScrollableContent: boolean
+  scrollEnabled: boolean
+  setScrollEnabled: (enabled: boolean, lockTo?: number) => void
+}
+
+/**
+ * Native gesture handling for Sheet ScrollView.
+ * Returns responder props for the ScrollView component.
+ */
+export function useSheetScrollViewGestures({
+  scrollBridge,
+  hasScrollableContent,
+  scrollEnabled,
+  setScrollEnabled,
+}: UseSheetScrollViewGesturesProps) {
+  const state = useRef<ResponderState>({
+    lastPageY: 0,
+    dragAt: 0,
+    dys: [],
+    isScrolling: false,
+    isDraggingScrollArea: false,
+    scrollEngaged: false,
+    prevScrollY: 0,
+    handoffOccurred: false,
+    handoffDragOffset: 0,
+  })
+
+  const release = () => {
+    const s = state.current
+    if (!s.isDraggingScrollArea) return
+
+    s.isDraggingScrollArea = false
+    scrollBridge.scrollStartY = -1
+    scrollBridge.scrollLock = false
+    s.isScrolling = false
+    s.scrollEngaged = false
+    s.prevScrollY = 0
+    s.handoffOccurred = false
+    s.handoffDragOffset = 0
+    setScrollEnabled(true)
+
+    let vy = 0
+    if (s.dys.length) {
+      const recentDys = s.dys.slice(-10)
+      const dist = recentDys.reduce((a, b) => a + b, 0)
+      vy = (dist / recentDys.length) * 0.04
+    }
+    s.dys = []
+
+    scrollBridge.release({ dragAt: s.dragAt, vy })
+  }
+
+  const onStartShouldSetResponder = () => {
+    const s = state.current
+    scrollBridge.scrollStartY = -1
+    s.isDraggingScrollArea = true
+    s.scrollEngaged = scrollBridge.y > 0
+    s.prevScrollY = scrollBridge.y
+    s.handoffOccurred = false
+    s.handoffDragOffset = 0
+    return false
+  }
+
+  const onMoveShouldSetResponder = (e: GestureResponderEvent) => {
+    if (!scrollEnabled) return false
+    const s = state.current
+    const { pageY } = e.nativeEvent
+    if (s.lastPageY === 0) {
+      s.lastPageY = pageY
+      return false
+    }
+    return Math.abs(pageY - s.lastPageY) > 10
+  }
+
+  const onResponderMove = (e: GestureResponderEvent) => {
+    const s = state.current
+    const { pageY } = e.nativeEvent
+
+    if (!s.isScrolling && scrollBridge.scrollStartY === -1) {
+      scrollBridge.scrollStartY = pageY
+      s.lastPageY = pageY
+    }
+
+    const dragAt = pageY - scrollBridge.scrollStartY
+    const dy = pageY - s.lastPageY
+    s.lastPageY = pageY
+    const isDraggingDown = dy > 0
+    const isPaneAtTop = scrollBridge.paneY <= scrollBridge.paneMinY + 5
+    const currentScrollY = scrollBridge.y
+
+    if (currentScrollY > 0) s.scrollEngaged = true
+
+    const wasScrolledNowAtZero =
+      s.scrollEngaged && s.prevScrollY > 0 && currentScrollY <= 0
+
+    if (wasScrolledNowAtZero && !s.handoffOccurred) {
+      s.handoffOccurred = true
+      s.handoffDragOffset = 0
+    }
+
+    s.prevScrollY = currentScrollY
+
+    let panHandles = false
+    if (!isPaneAtTop) {
+      panHandles = isDraggingDown ? currentScrollY <= 0 || !hasScrollableContent : true
+    } else if (isDraggingDown) {
+      if (currentScrollY > 0 && hasScrollableContent && !s.handoffOccurred) {
+        panHandles = false
+      } else {
+        panHandles = s.handoffOccurred || wasScrolledNowAtZero || currentScrollY <= 0
+      }
+    } else {
+      panHandles = !hasScrollableContent
+      if (!panHandles) {
+        s.isScrolling = true
+        scrollBridge.scrollLock = true
+        setScrollEnabled(true)
+        return
+      }
+    }
+
+    if (panHandles) {
+      setScrollEnabled(false)
+      let effectiveDragAt = dragAt
+      if (s.handoffOccurred) {
+        s.handoffDragOffset += dy
+        effectiveDragAt = s.handoffDragOffset
+      }
+      scrollBridge.drag(effectiveDragAt)
+      s.dragAt = effectiveDragAt
+      s.dys.push(dy)
+      if (s.dys.length > 100) s.dys = s.dys.slice(-10)
+    } else {
+      setScrollEnabled(true)
+    }
+  }
+
+  return {
+    onResponderRelease: release,
+    onStartShouldSetResponder,
+    onMoveShouldSetResponder,
+    onResponderMove,
+  }
+}