react-native-gtkx 0.2.0-alpha.2 → 0.3.0-alpha.1

package/dist/components/scroll-view.js

@@ -1,11 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Children, createContext, forwardRef, useContext, useImperativeHandle, useLayoutEffect, useRef, useState, } from "react";
 import { splitStyle, StyleSheet } from "../style/index";
-import { Gtk, GtkBox, GtkScrolledWindow, queueAllocate, queueResize, useSignal, } from "../gtkx/bridge/index";
+import { Gdk, Gtk, GtkBox, GtkScrolledWindow, queueAllocate, queueResize, useSignal, } from "../gtkx/bridge/index";
 import { ensurePerfReporter, perfAddTime, perfCount, perfEnabled, perfFrameTick, perfNow, } from "../perf";
+import { useResponder } from "../responder/use-responder";
 import { HostNodeContext } from "./host-node";
+import { createMeasureHandle, registerHandleWidget, } from "./measure";
 import { deferDuringAllocate, setStoredOffset } from "./rect-store";
+import { scrollPhaseSink } from "./scroll-phase";
 import { useLayoutChild, useRnContainer, } from "./use-layout-child";
+import { createWheelScrollSession } from "./wheel-scroll-session";
 export const StickyRegistryContext = createContext(null);
 // A wrapper around a sticky child: a plain container that reports its layout
 // and widget into the registry, so the scroll handler can translate/reorder
@@ -42,7 +46,7 @@ export const StickySlot = ({ stickyKey, style, top, onLayout, children, }) => {
 // node inside the same engine: the content's RnGtkxLayout measures the engine
 // content size (which grows past the viewport — that IS the scroll range;
 // overflow: scroll on the outer node) and the scrolled window pans it.
-export const ScrollView = forwardRef(({ style, contentContainerStyle, horizontal = false, stickyHeaderIndices, onScroll, onContentSizeChange, onLayout, children, testID, }, handleRef) => {
+export const ScrollView = forwardRef(({ style, contentContainerStyle, horizontal = false, stickyHeaderIndices, onScroll, onScrollBeginDrag, onScrollEndDrag, onMomentumScrollBegin, onMomentumScrollEnd, onContentSizeChange, onLayout, children, testID, ...responderProps }, handleRef) => {
     const outerRef = useRef(null);
     const contentRef = useRef(null);
     const [scrolled, setScrolled] = useState(null);
@@ -50,11 +54,39 @@ export const ScrollView = forwardRef(({ style, contentContainerStyle, horizontal
         // Yoga unconstrains a scroll node's MAIN axis — align it with the
         // scroll direction or a horizontal list's content clamps to the
         // viewport width (hadjustment upper == page).
+        //
+        // `flexGrow: 1, flexShrink: 1` is RN's own base style for the scroller
+        // (`styles.baseVertical` / `baseHorizontal` in ScrollView.js, applied as
+        // `StyleSheet.compose(baseStyle, this.props.style)` — hence base first,
+        // the app's style wins). The shrink half is what turns a scrollable with
+        // NO style of its own into a viewport: a flex item defaults to
+        // flexShrink 0 on RN's Yoga config, so without this the scroller sizes
+        // to its content, outgrows a bounded parent and its scroll range stays
+        // empty. It cost a whole investigation once: `@gorhom/bottom-sheet`
+        // hands its list down unstyled, so the sheet's scroll lock had nothing
+        // to lock — the list never received a scroll event because it had never
+        // become a viewport.
+        //
+        // Composing base-first does NOT protect an explicit `height`: grow and
+        // height are different properties, so nothing overrides anything — the
+        // height is the flex BASIS and grow expands from it, and a scroller with
+        // `height: 200` in a 400px column lays out at 400. RN does the same
+        // (same base, same order, same node, same Yoga resolution), so this is
+        // parity and not a bug; docs/api.md says so where people will look.
+        // Bound the PARENT to bound the viewport.
         style: [
+            { flexGrow: 1, flexShrink: 1 },
             style,
             { overflow: "scroll", flexDirection: horizontal ? "row" : "column" },
         ],
         onLayout,
+        // RN semantics: a ScrollView CLIPS its content. Containers paint-
+        // overflow by default, so without this the scrolled-away content (e.g.
+        // the original of a pinned sticky header) keeps drawing past the scroll
+        // area's edges. The `overflow: "scroll"` above would now clip the
+        // viewport on its own, but a viewport that clips only while nobody
+        // overrides the style is not a contract.
+        alwaysClips: true,
     });
     const [contentNode] = useState(() => host.engine.createNode());
     // Sticky positions are computed INSIDE the same allocation pass that
@@ -68,13 +100,6 @@ export const ScrollView = forwardRef(({ style, contentContainerStyle, horizontal
             }
         },
     });
-    // RN semantics: a ScrollView CLIPS its content. Branch B made containers
-    // paint-overflow by default, so without this the scrolled-away content
-    // (e.g. the original of a pinned sticky header) keeps drawing past the
-    // scroll area's edges.
-    useLayoutEffect(() => {
-        outerRef.current?.setOverflow(Gtk.Overflow.HIDDEN);
-    }, []);
     useLayoutEffect(() => {
         outerNode.insertChild(contentNode, 0);
         contentNode.setCommit(() => {
@@ -103,39 +128,74 @@ export const ScrollView = forwardRef(({ style, contentContainerStyle, horizontal
     useLayoutEffect(() => {
         contentNode.setStyle({
             flexDirection: horizontal ? "row" : "column",
-            alignItems: "flex-start",
+            // RN's content container is a plain `View`, and a `View`'s default
+            // `alignItems` is `stretch` — so a vertical ScrollView's children are
+            // as wide as the viewport unless they say otherwise. This used to be
+            // `flex-start`, which made every child shrink to its intrinsic width
+            // and any `flex: 1` inside it collapse to zero.
+            //
+            // It was found twice. First by `Sortable`, whose rows rendered as
+            // bare drag handles with no text (docs/research/drag-and-drop.md
+            // recorded it as a probable ScrollView parity bug and did not act on
+            // it, because changing a shared default under every example was not
+            // that epic's business). Then by porting
+            // `react-native-reanimated-dnd`'s example app, where it broke
+            // seventeen screens at once — at which point "a ported app changes
+            // nothing in its source" was simply false, and the default was the
+            // thing that was wrong.
+            //
+            // An app that wants the old behaviour writes it, exactly as it would
+            // on iOS and Android: `contentContainerStyle={{ alignItems:
+            // "flex-start" }}`.
+            alignItems: "stretch",
             ...contentLayout,
         });
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [contentNode, contentKey]);
-    useImperativeHandle(handleRef, () => ({
-        scrollTo({ x, y }) {
-            const widget = outerRef.current;
-            if (!widget) {
-                return;
-            }
-            if (y !== undefined) {
-                widget.getVadjustment()?.setValue(y);
-            }
-            if (x !== undefined) {
-                widget.getHadjustment()?.setValue(x);
-            }
-        },
-        scrollToEnd() {
-            const widget = outerRef.current;
-            const adjustment = horizontal
-                ? widget?.getHadjustment()
-                : widget?.getVadjustment();
-            if (adjustment) {
-                adjustment.setValue(adjustment.getUpper() - adjustment.getPageSize());
-            }
-        },
-    }));
+    // On the SCROLLED WINDOW, not on the content box: that is the widget the
+    // handle stands for, the widget a `GestureDetector` measures its gesture's
+    // view against, and the widget whose own kinetics a `Gesture.Native()`
+    // over this scrollable is talking about.
+    useResponder(outerRef, responderProps);
+    useImperativeHandle(handleRef, () => {
+        const handle = {
+            ...createMeasureHandle(outerRef, outerNode),
+            scrollTo({ x, y }) {
+                const widget = outerRef.current;
+                if (!widget) {
+                    return;
+                }
+                if (y !== undefined) {
+                    widget.getVadjustment()?.setValue(y);
+                }
+                if (x !== undefined) {
+                    widget.getHadjustment()?.setValue(x);
+                }
+            },
+            scrollToEnd() {
+                const widget = outerRef.current;
+                const adjustment = horizontal
+                    ? widget?.getHadjustment()
+                    : widget?.getVadjustment();
+                if (adjustment) {
+                    adjustment.setValue(adjustment.getUpper() - adjustment.getPageSize());
+                }
+            },
+        };
+        // Spreading built a NEW object, and the widget lookup is keyed by
+        // handle identity — without this the composed handle is a stranger to
+        // measure.ts.
+        registerHandleWidget(handle, outerRef);
+        return handle;
+    });
     // --- sticky headers -------------------------------------------------
     // The RN model, faithfully: the REAL child is translated (no duplicate,
-    // state preserved). RN gives the pinned cell a zIndex; GTK's z-order is
-    // sibling paint order, so the active slot is reordered to be the LAST
-    // content child while pinned and restored afterwards. Per-frame movement
+    // state preserved). RN gives the pinned cell a zIndex; this reorders the
+    // active slot to be the LAST content child while pinned and restores it
+    // afterwards, which predates `zIndex` working (gtkx/bridge/view-box.ts)
+    // and is kept because it is exact: the slots here are the ScrollView's own
+    // and their Yoga order is rebuilt from the same list, so the reorder that
+    // would be a hazard for arbitrary app children is not one for these. Per-frame movement
     // goes through the rect-store offset fast path — zero React work while
     // scrolling.
     const stickySet = stickyHeaderIndices ?? [];
@@ -232,18 +292,20 @@ export const ScrollView = forwardRef(({ style, contentContainerStyle, horizontal
             }
         }
     };
-    const emitScroll = () => {
-        if (!onScroll) {
-            return;
-        }
+    // The one place the payload is read off the widget, shared by `onScroll`
+    // and by all four phases — RN hands the same `ScrollEvent` to every one
+    // of them, and reading it twice would be two sets of FFI calls for one
+    // truth. Null when there is nothing honest to report yet (no widget, or
+    // a content size the engine has not committed).
+    const readScrollEvent = () => {
         const widget = outerRef.current;
         const contentRect = contentNode.getRect();
         if (!widget || !contentRect) {
-            return;
+            return null;
         }
         const hadjustment = widget.getHadjustment();
         const vadjustment = widget.getVadjustment();
-        onScroll({
+        return {
             nativeEvent: {
                 contentOffset: {
                     x: hadjustment?.getValue() ?? 0,
@@ -255,7 +317,16 @@ export const ScrollView = forwardRef(({ style, contentContainerStyle, horizontal
                     height: vadjustment?.getPageSize() ?? 0,
                 },
             },
-        });
+        };
+    };
+    const emitScroll = () => {
+        if (!onScroll) {
+            return;
+        }
+        const event = readScrollEvent();
+        if (event) {
+            onScroll(event);
+        }
     };
     const adjustment = horizontal
         ? (scrolled?.getHadjustment() ?? null)
@@ -273,6 +344,270 @@ export const ScrollView = forwardRef(({ style, contentContainerStyle, horizontal
         emitScroll();
         perfAddTime("scroll.js", perfNow() - start);
     };
+    // --- the four scroll phases -----------------------------------------
+    //
+    // What GTK actually reports, measured on 4.22.4 under a real pointer
+    // (docs/research/scroll-phases.md, and the trace is in
+    // tests/gtk/components/scroll-phases.gtk.test.tsx):
+    //
+    //   - a mouse WHEEL emits `::scroll` per detent and NOTHING around it.
+    //     GTK gives us no sequence, so while a consumer asks for begin/end we
+    //     synthesize a desktop scroll SESSION: begin before the first detent
+    //     mutates the adjustment, end after a measured idle window, and no
+    //     momentum. This is an intentional desktop extension — RN has no
+    //     wheel — and is what lets a phase-aware consumer capture the offset
+    //     it is about to constrain instead of discovering it one event late.
+    //   - a touchpad GLIDE emits `::scroll-begin`, a stream of `::scroll`,
+    //     `::scroll-end` and `::decelerate` — a real sequence with a real
+    //     beginning and end — and the scrolled window's own kinetic
+    //     animation then carries the adjustment on for another second or so.
+    //     All four phases exist, and all four are reported.
+    //
+    // Drag maps onto the scroll SEQUENCE rather than onto a finger on the
+    // content: `::scroll-begin` is "the user started driving this scroller",
+    // which is what a consumer of `onScrollBeginDrag` acts on and is as close
+    // as a device that never touches the content can get. That is the one
+    // approximation here, and it is named in docs/api.md.
+    //
+    // Momentum is read off the ADJUSTMENT, not off `::decelerate`. The
+    // controller emits `decelerate` at every `scroll-end` — it reports the
+    // velocity it measured, not a decision to coast — while the scrolled
+    // window decides for itself whether that velocity is worth animating. RN
+    // fires `onMomentumScrollBegin` only when the view actually keeps
+    // moving, so the honest source is the movement itself.
+    const phaseSink = scrollPhaseSink(onScroll);
+    // `wants()` rather than the sink's mere presence: every Reanimated scroll
+    // handler carries one, and most of them ask for nothing but `onScroll`.
+    // Asking is what keeps the common case free.
+    const wantsPhases = Boolean(onScrollBeginDrag ||
+        onScrollEndDrag ||
+        onMomentumScrollBegin ||
+        onMomentumScrollEnd ||
+        phaseSink?.wants());
+    // GTK brackets touchpad gestures for us. A wheel has only detents, so the
+    // begin/end extension below needs to see those detents — but only when a
+    // consumer asks for either end of the session. A momentum-only handler
+    // still pays no JS call per wheel event, because a wheel never coasts.
+    const wantsWheelSessions = Boolean(onScrollBeginDrag ||
+        onScrollEndDrag ||
+        phaseSink?.wants("beginDrag") ||
+        phaseSink?.wants("endDrag"));
+    // Read per event rather than captured, exactly as `useAnimatedScrollHandler`
+    // does it: a re-render that changed a handler must be picked up without
+    // tearing the GTK controller down and building a new one.
+    const phaseHandlers = useRef({
+        onScrollBeginDrag,
+        onScrollEndDrag,
+        onMomentumScrollBegin,
+        onMomentumScrollEnd,
+        phaseSink,
+        readScrollEvent,
+    });
+    phaseHandlers.current = {
+        onScrollBeginDrag,
+        onScrollEndDrag,
+        onMomentumScrollBegin,
+        onMomentumScrollEnd,
+        phaseSink,
+        readScrollEvent,
+    };
+    useLayoutEffect(() => {
+        // The whole cost story is this early return. No phase handler means no
+        // controller, no signal, no tick callback and no bookkeeping — the
+        // widget is byte-for-byte the one this component built before the
+        // phases existed.
+        if (!wantsPhases) {
+            return;
+        }
+        const widget = scrolled;
+        if (!widget) {
+            return;
+        }
+        const emitPhase = (phase) => {
+            const handlers = phaseHandlers.current;
+            const event = handlers.readScrollEvent();
+            if (!event) {
+                return;
+            }
+            if (phase === "beginDrag") {
+                handlers.onScrollBeginDrag?.(event);
+            }
+            else if (phase === "endDrag") {
+                handlers.onScrollEndDrag?.(event);
+            }
+            else if (phase === "momentumBegin") {
+                handlers.onMomentumScrollBegin?.(event);
+            }
+            else {
+                handlers.onMomentumScrollEnd?.(event);
+            }
+            handlers.phaseSink?.deliver(phase, event);
+        };
+        const axis = horizontal
+            ? widget.getHadjustment()
+            : widget.getVadjustment();
+        // Momentum is watched on the ADJUSTMENT, with two timers and no tick
+        // callback. A frame-polling watcher was the first shape and it was
+        // wrong twice over: it burns a callback per frame for the length of
+        // every coast, and it counts FRAMES, which is not a unit — under the
+        // headless compositor the frame clock free-runs at ~106 ticks per
+        // millisecond (measured, docs/research/scroll-phases.md), so a
+        // four-frame grace expired in microseconds. Wall time means the same
+        // thing everywhere.
+        //
+        // Milliseconds to wait after `::scroll-end` for the scrolled window's
+        // kinetic animation to take over before concluding it never will.
+        // Measured handoff: `::scroll-end` at 1921.9 ms, first inertial value
+        // change at 1927.5 ms — 5.6 ms. 120 is slack, not a guess.
+        const handoffMs = 120;
+        // Milliseconds of a motionless adjustment that end the momentum. GTK's
+        // deceleration steps the value every frame right to the end (16.7 ms
+        // apart in the trace), so 60 ms is three and a half missed steps.
+        const restMs = 60;
+        let watching = false;
+        let coasting = false;
+        let lastMoveAt = 0;
+        let handoffTimer = null;
+        let restTimer = null;
+        const clearTimers = () => {
+            if (handoffTimer !== null) {
+                clearTimeout(handoffTimer);
+                handoffTimer = null;
+            }
+            if (restTimer !== null) {
+                clearTimeout(restTimer);
+                restTimer = null;
+            }
+        };
+        // Re-armed for the REMAINING idle time rather than reset on every step,
+        // so the number of timers a coast costs is bounded by its duration
+        // (one per `restMs`) and not by how many times the adjustment moved.
+        // The difference is not academic: under the headless compositor's
+        // free-running frame clock a single coast steps the value ~150,000
+        // times, and a clear-and-rearm per step is 150,000 timers.
+        const checkRest = () => {
+            const idle = perfNow() - lastMoveAt;
+            if (idle < restMs) {
+                restTimer = setTimeout(checkRest, restMs - idle);
+                return;
+            }
+            restTimer = null;
+            stopMomentumWatch();
+            emitPhase("momentumEnd");
+        };
+        const onCoastStep = () => {
+            lastMoveAt = perfNow();
+            if (coasting) {
+                return;
+            }
+            coasting = true;
+            if (handoffTimer !== null) {
+                clearTimeout(handoffTimer);
+                handoffTimer = null;
+            }
+            emitPhase("momentumBegin");
+            restTimer = setTimeout(checkRest, restMs);
+        };
+        const stopMomentumWatch = () => {
+            clearTimers();
+            if (watching) {
+                axis?.off("value-changed", onCoastStep);
+                watching = false;
+            }
+            coasting = false;
+        };
+        const watchMomentum = () => {
+            if (watching) {
+                return;
+            }
+            watching = true;
+            axis?.on("value-changed", onCoastStep);
+            handoffTimer = setTimeout(() => {
+                handoffTimer = null;
+                if (!coasting) {
+                    // The scroller came to rest with the drag. No inertia, so no
+                    // momentum pair — which is RN's behaviour too.
+                    stopMomentumWatch();
+                }
+            }, handoffMs);
+        };
+        const controller = Gtk.EventControllerScroll.new(
+        // An axis flag is REQUIRED, and not for the deltas: measured, a
+        // controller created with `KINETIC` alone emits nothing at all — not
+        // even `::scroll-begin`. `::scroll` is therefore emitted. It stays
+        // unconnected unless somebody asks for begin/end: only then does a
+        // wheel detent enter JS to maintain the desktop session below; a
+        // momentum-only or untracked scroller keeps the old empty C signal
+        // path.
+        Gtk.EventControllerScrollFlags.BOTH_AXES |
+            Gtk.EventControllerScrollFlags.KINETIC);
+        // CAPTURE, so the phase is reported before the scrolled window's own
+        // controller acts on the same event and moves the adjustment. Nothing
+        // here handles the event, so propagation is untouched either way.
+        controller.setPropagationPhase(Gtk.PropagationPhase.CAPTURE);
+        const beginDrag = () => {
+            // A new drag during a coast: RN ends the momentum before beginning
+            // the drag, so a consumer never sees two live phases at once.
+            if (coasting) {
+                stopMomentumWatch();
+                emitPhase("momentumEnd");
+            }
+            else {
+                stopMomentumWatch();
+            }
+            emitPhase("beginDrag");
+        };
+        // A wheel gives GTK no begin/end signals. Group its detents into one
+        // user-driven session, ending after an idle interval longer than the
+        // ordinary detent spacing measured in docs/research/scroll-phases.md
+        // (20–33 ms in the trace). The callback runs in CAPTURE, so beginDrag
+        // sees the PRE-scroll offset before GtkScrolledWindow mutates its
+        // adjustment and emits the onScroll callback that consumes the context.
+        const wheelSession = createWheelScrollSession(beginDrag, () => emitPhase("endDrag"));
+        // A touchpad brackets itself, so its sequence owns the session while it
+        // runs. Two live sessions at once would hand a consumer a second
+        // `beginDrag` before the first `endDrag` — which is exactly the state
+        // gorhom's lock reads to decide where to pin its list.
+        let nativeSequence = false;
+        const onScrollBegin = () => {
+            nativeSequence = true;
+            // A wheel burst may still be waiting out its idle timer.
+            wheelSession.finish();
+            beginDrag();
+        };
+        const onScrollEnd = () => {
+            nativeSequence = false;
+            emitPhase("endDrag");
+            watchMomentum();
+        };
+        const onScroll = () => {
+            if (!wantsWheelSessions ||
+                nativeSequence ||
+                controller.getUnit() !== Gdk.ScrollUnit.WHEEL) {
+                return false;
+            }
+            wheelSession.detent();
+            // Observe only. GtkScrolledWindow still receives and applies the
+            // detent, which is what makes this phase seam transparent.
+            return false;
+        };
+        controller.on("scroll-begin", onScrollBegin);
+        controller.on("scroll-end", onScrollEnd);
+        if (wantsWheelSessions) {
+            controller.on("scroll", onScroll);
+        }
+        widget.addController(controller);
+        return () => {
+            controller.off("scroll-begin", onScrollBegin);
+            controller.off("scroll-end", onScrollEnd);
+            if (wantsWheelSessions) {
+                controller.off("scroll", onScroll);
+            }
+            wheelSession.dispose();
+            widget.removeController(controller);
+            stopMomentumWatch();
+        };
+    }, [scrolled, wantsPhases, wantsWheelSessions, horizontal]);
     // Content-size reports dedupe on the engine rect: "changed" also fires
     // for pure viewport (page-size) changes, which RN does not report.
     const lastContentSize = useRef({ width: -1, height: -1 });