gui/pkgs/ui/sheet/next.md

Sheet ScrollView Gesture Handoff - Next Steps

Current Limitation

The Sheet + ScrollView gesture coordination on native iOS has limitations because Gui uses React Native's built-in PanResponder, while iOS's UIScrollView gesture recognizers fire BEFORE the RN responder system can claim the gesture.

This causes:

• Minor scroll "flicker" when starting to drag down from scroll top
• Imperfect handoff between scroll and sheet drag gestures

Ideal Solution: react-native-gesture-handler Integration

Both gorhom/bottom-sheet and react-native-actions-sheet solve this by using react-native-gesture-handler which provides:

1. simultaneousHandlers - allows coordinating multiple gesture recognizers
2. GestureDetector with worklets - can check conditions and decide who handles gesture before it starts
3. Native gesture coordination - works at the iOS/Android gesture recognizer level, not the JS responder level

Proposed API

import { setupGestureHandler } from '@hanzogui/sheet'
import { GestureHandlerRootView } from 'react-native-gesture-handler'

// Call once at app startup (optional - falls back to PanResponder)
setupGestureHandler({
  // Pass the gesture handler module so we don't add it as a hard dependency
  GestureDetector: require('react-native-gesture-handler').GestureDetector,
  Gesture: require('react-native-gesture-handler').Gesture,
})

// Then wrap app
export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <YourApp />
    </GestureHandlerRootView>
  )
}

Implementation Notes

If setupGestureHandler() is called:

• Use GestureDetector with Gesture.Pan() instead of PanResponder
• Use simultaneousHandlers to coordinate with ScrollView's gesture
• Implement blockPan flag pattern from actions-sheet for smooth handoff

If not called:

• Fall back to current PanResponder implementation
• Accept the minor limitations on native

References

• gorhom/bottom-sheet: Uses Reanimated worklets + gesture handler
• react-native-actions-sheet: Uses blockPan flag pattern with gesture handler
• Both are MIT licensed and can be used as reference

Files to Modify

• SheetImplementationCustom.tsx - Replace PanResponder with GestureDetector
• SheetScrollView.tsx - Use useScrollHandlers() pattern from actions-sheet
• Add setupGestureHandler.ts for optional gesture handler registration

Test Case

There's a test case at apps/kitchen-sink/src/usecases/SheetScrollableDrag.tsx that demonstrates the bug and can be used to verify fixes. It's not exported in the main navigation but can be accessed directly for testing.

Attempted Fixes

1. Native scroll enable/disable based on pane position - Tried disabling scroll when sheet is not at top position, but this completely broke scrolling because the initial pane position values aren't set correctly on mount.

2. PaneY change listeners - Added onPaneYChange/setPaneY to ScrollBridge to notify ScrollView of position changes during drag, but the fundamental issue remains that iOS UIScrollView gesture recognizers fire before RN's responder system.

The core issue is architectural: React Native's PanResponder cannot coordinate with iOS's native UIScrollView gesture recognizers at the right level. The only real solution is react-native-gesture-handler integration.