Feature Request: Ability to detect scroll events

[lbeus]

I'm integrating native player which is supposed to be used to play audio resources which are distributed as part of EPUB document and referenced in reading order documents. Player preview is supposed to hide/show as you scroll vertically up/down through XHTML document.

Suggestion is to add scroll callback method to VisualNavigatorDelegate as implemented in PR
func navigator(_ navigator: any VisualNavigator, didScrollIn direction: ScrollDirection)

One more use case where this event could be used is when integrating app analytics with the reader.

[mickael-menu]

Thanks for the feature request. Exposing scroll events is something we can support, but we'd want to keep the API surface minimal and avoid leaking implementation details like UIScrollView.

Behavior to support

The typical use case for scroll events is hiding/showing UI chrome (navigation bar, audio player, etc.) following the pattern used by Safari on iOS:

• Scrolling forward (toward more content): hide the bar immediately.
• Scrolling backward (toward the beginning): show the bar, but only after dragging past a distance threshold to avoid triggering on small jitters.
• Flick gesture: if the user lifts their finger with enough velocity in either direction, commit to hiding or showing regardless of distance.
• Direction reversal: reset the accumulated distance, so the threshold is relative to where the user changed direction.

To support this, the app needs exactly two pieces of information:

1. The drag delta in points, continuously, but only while the user's finger is on screen (not during momentum deceleration).
2. The velocity at the moment the user lifts their finger.

Proposed API

Two optional methods on VisualNavigatorDelegate, with a sign convention where positive = forward progression through the content:

public protocol VisualNavigatorDelegate: NavigatorDelegate {
    ...
    
    /// Called continuously while the user drags the content.
    ///
    /// `delta` is the distance in points along the scroll axis
    /// since the last call. Positive values indicate forward
    /// progression through the content.
    ///
    /// Not called during momentum deceleration after the user
    /// lifts their finger.
    func navigator(_ navigator: any VisualNavigator, didDragBy delta: CGFloat)
    
    /// Called when the user lifts their finger after dragging.
    ///
    /// `velocity` is in points per second along the scroll axis.
    /// Positive values indicate forward momentum.
    func navigator(_ navigator: any VisualNavigator, didEndDraggingWithVelocity velocity: CGFloat)
}

Usage example, for a Safari-like bar hiding:

// Points of sustained drag before showing
private let dragThreshold: CGFloat = 40
// Points/sec to trigger on flick
private let velocityThreshold: CGFloat = 500

private var accumulatedDelta: CGFloat = 0

func navigator(_ navigator: any VisualNavigator, didDragBy delta: CGFloat) {
    // Reset accumulator on direction change
    if (delta > 0) != (accumulatedDelta > 0) {
        accumulatedDelta = 0
    }
    accumulatedDelta += delta
    
    if accumulatedDelta > 0 {
        // Scrolling forward -> hide immediately
        hideBar()
    } else if accumulatedDelta < -dragThreshold {
        // Scrolling backward past threshold -> show
        showBar()
    }
}

func navigator(_ navigator: any VisualNavigator, didEndDraggingWithVelocity velocity: CGFloat) {
    accumulatedDelta = 0
    
    if velocity > velocityThreshold {
        hideBar()
    } else if velocity < -velocityThreshold {
        showBar()
    }
}

The asymmetry is intentional: hiding is immediate because the user is actively reading and the chrome should get out of the way, while showing requires sustained intent to avoid false triggers from small scroll adjustments.

@lbeus Would this API cover your use cases? If so, we can rework PR #701 along these lines.

[lbeus]

@mickael-menu Thank you for your input and suggestion. This API will definitely cover my use cases 👍