@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/usePanZoom.js

@@ -0,0 +1,175 @@
+// Navigation gestures for a linear view, as two hooks a host can bind to an
+// element it owns.
+//
+// This is the wiring between a pointing device and `zoomTo`/`horizontalScroll`,
+// and it is the part of embedding a view that has no interesting variants: a
+// wheel means the same thing in every genome browser, and getting it wrong is
+// mostly invisible until a trackpad or a touchscreen is involved. JBrowse's own
+// LinearGenomeView binds `useWheelZoom` to its tracks area, and an embedder
+// building their own chrome around a view binds `usePanZoom` to theirs — same
+// gestures, same feel, one implementation.
+//
+// Bind these to the data, not to the whole view. The chrome you leave out is
+// the only surface a scroll-to-zoom user has left for scrolling the page: no
+// modifier can serve as one, because browsers turn shift+wheel into horizontal
+// scroll, ctrl/meta+wheel is how a trackpad reports a pinch, and Firefox binds
+// alt+wheel to history navigation.
+//
+// The wheel half is `createWheelZoomController` (wheelZoom.ts), which is where
+// the gesture decision matrix, the rAF batching and the zoom rate limit live.
+//
+// Scroll-to-zoom is off by default and so has to be found: what says so is the
+// labelled toggle every view header carries (`ui/ScrollZoomToggle`), whose
+// tooltip is also where ctrl/⌘+scroll — which zooms whatever the preference
+// says — is named.
+import { useEffect, useRef } from 'react';
+import { createWheelZoomController } from './wheelZoom.js';
+/**
+ * Wheel zoom and side-scroll, bound to `ref` for as long as the component
+ * lives.
+ *
+ * The listener is registered on the element directly and non-passively, which
+ * is not a style preference: React registers `wheel` at the root as a *passive*
+ * listener, so a handler installed through the `onWheel` prop cannot
+ * `preventDefault`, and the gesture would drive the page out from under you at
+ * the same time as it drove the view.
+ */
+export function useWheelZoom(ref, view) {
+    useEffect(() => {
+        const element = ref.current;
+        return element
+            ? createWheelZoomController({
+                element,
+                // the view fills its own area and doesn't move under the cursor, so a
+                // mouseleave here really means the gesture belongs to the page now
+                releaseOnPointerLeave: true,
+                resolveTarget: () => ({
+                    views: [view],
+                    scrollZoom: !!view.scrollZoom,
+                    originElement: () => element,
+                }),
+            })
+            : undefined;
+    }, [ref, view]);
+}
+// How far the pointer has to travel before a press counts as a pan rather than
+// a click. Under this, the gesture is still a click and whatever is underneath
+// gets to keep it.
+const DRAG_THRESHOLD_PX = 4;
+/**
+ * Every navigation gesture for a view, on one element: wheel zoom, side-scroll,
+ * and click-drag panning.
+ *
+ * ```tsx
+ * const ref = useWidthSetter(view)
+ * const { containerProps } = usePanZoom(ref, view)
+ * return (
+ *   <div ref={ref} {...containerProps}>
+ *     …tracks…
+ *   </div>
+ * )
+ * ```
+ *
+ * **`touch-action: none` comes with it**, written onto `ref`'s element. Without
+ * it a browser claims a touch drag as a page scroll, the pointer stream never
+ * arrives, and the gestures below are bound and dead — on a phone only, so a
+ * demo written and tested on a desktop is inert with nothing in the console.
+ * Asking the host for it was one line of documentation against a silent failure
+ * on half the devices there are.
+ *
+ * Set imperatively rather than handed back as a style, because a host that
+ * spreads its own `style` on the same element would drop it. React writes only
+ * the style properties its own `style` prop names, so this survives every
+ * render that does not mention `touchAction` — and a host that does name one
+ * wins, which is the escape hatch. `touchAction` here is the other:
+ * `'pan-y'` for a view inside a long document that should still scroll the
+ * page vertically, or `false` to leave the property alone entirely.
+ *
+ * JBrowse's own view splits these across two elements (the wheel on the whole
+ * view, the drag on the tracks area, so a drag over the header does nothing) and
+ * so binds `useWheelZoom` plus its own `useSideScroll`. One element is the
+ * normal case for an embedder, and this is it.
+ */
+export function usePanZoom(ref, view, { touchAction = 'none', } = {}) {
+    // `x` is the last position a pan was applied from; `panning` is whether the
+    // press has travelled far enough to be a drag at all
+    const dragRef = useRef(undefined);
+    useWheelZoom(ref, view);
+    // restores rather than clears on the way out: the element may outlive this
+    // hook (a host that stops binding gestures without unmounting its container),
+    // and clearing would take a `touch-action` the host set for itself
+    useEffect(() => {
+        const element = ref.current;
+        if (!element || touchAction === false) {
+            return;
+        }
+        // `|| ''` because a CSSOM that does not implement `touch-action` answers
+        // `undefined` (jsdom does), and writing that back is a write of the string
+        // "undefined" rather than a clear
+        const previous = element.style.touchAction || '';
+        element.style.touchAction = touchAction;
+        return () => {
+            element.style.touchAction = previous;
+        };
+    }, [ref, touchAction]);
+    function endDrag(event) {
+        dragRef.current = undefined;
+        // release only what the move handler took — a press that stayed under the
+        // threshold never captured anything
+        if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+            event.currentTarget.releasePointerCapture(event.pointerId);
+        }
+    }
+    return {
+        containerProps: {
+            onPointerDown(event) {
+                // Leave the press alone when something else owns it: a control that
+                // claimed it (`[data-gesture-owner]`, JBrowse's marker on the parts
+                // that drag on their own — a display's vertical scrollbar, a resize
+                // handle), a button (the track-sizing button a display draws in its own
+                // corner), or a draggable element. `closest`, because the press usually
+                // lands on an icon inside the control. Shift is left alone too: it is
+                // what a range-select of the host's own would want, and it is what
+                // JBrowse's own view uses it for.
+                if (event.button !== 0 || event.shiftKey) {
+                    return;
+                }
+                if (event.target instanceof Element &&
+                    event.target.closest('button, [data-gesture-owner], [draggable="true"]')) {
+                    return;
+                }
+                // Note what this does *not* do: capture the pointer. See onPointerMove.
+                dragRef.current = { x: event.clientX, panning: false };
+            },
+            onPointerMove(event) {
+                const drag = dragRef.current;
+                if (!drag) {
+                    return;
+                }
+                if (!drag.panning) {
+                    if (Math.abs(event.clientX - drag.x) < DRAG_THRESHOLD_PX) {
+                        return;
+                    }
+                    // Past the threshold this is a pan, so take the pointer: the gesture
+                    // has to keep panning when the cursor leaves the element, and end
+                    // even if it is released outside the window.
+                    //
+                    // Capturing is deferred to here because it retargets the whole rest
+                    // of the gesture — including the `click` that ends it — at this
+                    // element. Capture on pointerdown instead and every click inside the
+                    // view lands here, so nothing underneath ever sees one: a display's
+                    // click-to-select-a-feature stops selecting. A press that never moves
+                    // never captures, and stays the click it looks like.
+                    drag.panning = true;
+                    event.currentTarget.setPointerCapture(event.pointerId);
+                }
+                view.horizontalScroll(drag.x - event.clientX);
+                drag.x = event.clientX;
+            },
+            // pointercancel as well as pointerup: a touch drag interrupted by the
+            // browser never fires `up`, and the drag would stay latched
+            onPointerUp: endDrag,
+            onPointerCancel: endDrag,
+        },
+    };
+}

package/esm/util/usePanelVirtualScroll.d.ts

@@ -0,0 +1,37 @@
+interface PanelScrollTarget {
+    scrollTop: number;
+    scrollableHeight: number;
+    setScrollTop: (n: number) => void;
+}
+/**
+ * Wheel gestures over a **scrolled canvas panel** — the alignments pileup and
+ * the canvas basic display: a plain wheel scrolls it, `shift` keeps scrolling it
+ * once `scrollZoom` has claimed the plain wheel for the view, and ctrl/meta is
+ * left to the browser and the view's pinch-zoom. Nothing here resizes anything.
+ *
+ * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
+ * DOM overflow container, so nothing scrolls them without this. The latch (inside
+ * `applyScroll`) owns `preventDefault` but never `stopPropagation`, so a diagonal
+ * wheel still bubbles its horizontal component to the LGV for panning.
+ *
+ * ADR-027 keeps wheel-*intent* dispatch per handler, because the panels do not
+ * agree on what a gesture means. This is the second of the two rules that
+ * survived that split — the row-stack rule (`useRowVirtualScroll`, where `shift`
+ * resizes) is the other — and the two displays sharing it had byte-identical
+ * copies differing only in which getter named the viewport. The canvas display
+ * converged here when it moved off a native overflow container; the ADR's table
+ * still described its pre-virtual-scroll rule and has been corrected.
+ *
+ * `scrollZoom` and `viewportHeight` are inputs rather than reads off the model,
+ * so core needs no view typing and each display keeps naming its own viewport
+ * (the pileup's excludes the sticky coverage band; the canvas display's is the
+ * whole track).
+ *
+ * `panel` is the element wrapping the canvas AND the DOM overlays drawn over it,
+ * never the canvas alone — see `useVirtualScrollWheel`, which says why.
+ */
+export declare function usePanelVirtualScroll(panel: HTMLElement | null, model: PanelScrollTarget, { viewportHeight, scrollZoom, }: {
+    viewportHeight: number;
+    scrollZoom: boolean;
+}): void;
+export {};

package/esm/util/usePanelVirtualScroll.js

@@ -0,0 +1,42 @@
+import { useVirtualScrollWheel } from './useVirtualScrollWheel.js';
+/**
+ * Wheel gestures over a **scrolled canvas panel** — the alignments pileup and
+ * the canvas basic display: a plain wheel scrolls it, `shift` keeps scrolling it
+ * once `scrollZoom` has claimed the plain wheel for the view, and ctrl/meta is
+ * left to the browser and the view's pinch-zoom. Nothing here resizes anything.
+ *
+ * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
+ * DOM overflow container, so nothing scrolls them without this. The latch (inside
+ * `applyScroll`) owns `preventDefault` but never `stopPropagation`, so a diagonal
+ * wheel still bubbles its horizontal component to the LGV for panning.
+ *
+ * ADR-027 keeps wheel-*intent* dispatch per handler, because the panels do not
+ * agree on what a gesture means. This is the second of the two rules that
+ * survived that split — the row-stack rule (`useRowVirtualScroll`, where `shift`
+ * resizes) is the other — and the two displays sharing it had byte-identical
+ * copies differing only in which getter named the viewport. The canvas display
+ * converged here when it moved off a native overflow container; the ADR's table
+ * still described its pre-virtual-scroll rule and has been corrected.
+ *
+ * `scrollZoom` and `viewportHeight` are inputs rather than reads off the model,
+ * so core needs no view typing and each display keeps naming its own viewport
+ * (the pileup's excludes the sticky coverage band; the canvas display's is the
+ * whole track).
+ *
+ * `panel` is the element wrapping the canvas AND the DOM overlays drawn over it,
+ * never the canvas alone — see `useVirtualScrollWheel`, which says why.
+ */
+export function usePanelVirtualScroll(panel, model, { viewportHeight, scrollZoom, }) {
+    useVirtualScrollWheel(panel, (e, applyScroll) => {
+        if ((scrollZoom && !e.shiftKey) || e.ctrlKey || e.metaKey) {
+            return;
+        }
+        applyScroll(e, {
+            scrollTop: model.scrollTop,
+            viewportHeight,
+            scrollableHeight: model.scrollableHeight,
+        }, n => {
+            model.setScrollTop(n);
+        });
+    });
+}

package/esm/util/usePointerDrag.d.ts

@@ -0,0 +1,37 @@
+import type React from 'react';
+/**
+ * Pointer-capture drag lifecycle shared by draggable UI (resize handles,
+ * scrollbars, rubberbands, pan). On pointerdown it captures the pointer on the
+ * event's element, so the returned `onPointerMove`/`onPointerUp` fire on that
+ * same element even when the pointer leaves it — no window/document listeners,
+ * and the capture auto-releases if the element unmounts mid-drag.
+ *
+ * `onDrag` gets the live React pointer event. React nulls `event.currentTarget`
+ * after the handler returns, so snapshot `clientX`/`clientY` (and any target
+ * geometry) into locals synchronously before deferring work into a
+ * requestAnimationFrame.
+ *
+ * **One drag belongs to one pointer, and only a primary press starts it.**
+ * `pointerdown` fires for a right-click and for every extra finger, and a
+ * handler that takes them all reads as two different bugs: a right-press starts
+ * a drag that then runs under its own context menu, and a second finger landing
+ * mid-drag re-anchors the gesture, so the next move jumps by the distance
+ * between the two fingers. Tracking which pointer owns the drag is also what
+ * makes the move handler safe, since an uncaptured second pointer over the same
+ * element reports moves to it. `usePanZoom` guards its own pan the same way.
+ *
+ * The caller still owns `touch-action: none` on the element — without it the
+ * browser claims a touch drag as a page scroll and no pointer stream arrives at
+ * all. It stays a style rather than riding in the returned props because a
+ * caller's own `style` would silently replace it.
+ */
+export declare function usePointerDrag({ onDragStart, onDrag, onDragEnd, }: {
+    onDragStart?: (event: React.PointerEvent) => void;
+    onDrag: (event: React.PointerEvent) => void;
+    onDragEnd?: (event: React.PointerEvent) => void;
+}): {
+    onPointerDown: (event: React.PointerEvent) => void;
+    onPointerMove: (event: React.PointerEvent) => void;
+    onPointerUp: (event: React.PointerEvent) => void;
+    onPointerCancel: (event: React.PointerEvent) => void;
+};

package/esm/util/usePointerDrag.js

@@ -0,0 +1,61 @@
+import { useRef } from 'react';
+import { useEventCallback } from './useEventCallback.js';
+/**
+ * Pointer-capture drag lifecycle shared by draggable UI (resize handles,
+ * scrollbars, rubberbands, pan). On pointerdown it captures the pointer on the
+ * event's element, so the returned `onPointerMove`/`onPointerUp` fire on that
+ * same element even when the pointer leaves it — no window/document listeners,
+ * and the capture auto-releases if the element unmounts mid-drag.
+ *
+ * `onDrag` gets the live React pointer event. React nulls `event.currentTarget`
+ * after the handler returns, so snapshot `clientX`/`clientY` (and any target
+ * geometry) into locals synchronously before deferring work into a
+ * requestAnimationFrame.
+ *
+ * **One drag belongs to one pointer, and only a primary press starts it.**
+ * `pointerdown` fires for a right-click and for every extra finger, and a
+ * handler that takes them all reads as two different bugs: a right-press starts
+ * a drag that then runs under its own context menu, and a second finger landing
+ * mid-drag re-anchors the gesture, so the next move jumps by the distance
+ * between the two fingers. Tracking which pointer owns the drag is also what
+ * makes the move handler safe, since an uncaptured second pointer over the same
+ * element reports moves to it. `usePanZoom` guards its own pan the same way.
+ *
+ * The caller still owns `touch-action: none` on the element — without it the
+ * browser claims a touch drag as a page scroll and no pointer stream arrives at
+ * all. It stays a style rather than riding in the returned props because a
+ * caller's own `style` would silently replace it.
+ */
+export function usePointerDrag({ onDragStart, onDrag, onDragEnd, }) {
+    const activePointerRef = useRef(undefined);
+    const startStable = useEventCallback((event) => {
+        onDragStart?.(event);
+    });
+    const dragStable = useEventCallback(onDrag);
+    const endStable = useEventCallback((event) => {
+        onDragEnd?.(event);
+    });
+    function stop(event) {
+        if (activePointerRef.current === event.pointerId) {
+            activePointerRef.current = undefined;
+            endStable(event);
+        }
+    }
+    return {
+        onPointerDown: (event) => {
+            if (event.button !== 0 || activePointerRef.current !== undefined) {
+                return;
+            }
+            activePointerRef.current = event.pointerId;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            startStable(event);
+        },
+        onPointerMove: (event) => {
+            if (activePointerRef.current === event.pointerId) {
+                dragStable(event);
+            }
+        },
+        onPointerUp: stop,
+        onPointerCancel: stop,
+    };
+}

package/esm/util/useRafCommit.d.ts

@@ -0,0 +1,4 @@
+export declare function useRafCommit(commit: (value: number) => void): {
+    schedule: (value: number) => void;
+    flush: () => void;
+};

package/esm/util/useRafCommit.js

@@ -0,0 +1,50 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { useEventCallback } from './useEventCallback.js';
+// Coalesce rapid value writes to a single commit per animation frame. High-
+// frequency DOM events (a thumb drag's pointermove, plus the browser's
+// coalesced pointer batches) can fire faster than the frame rate; committing
+// each synchronously reruns the downstream work — a canvas repaint, an overlay
+// reconciliation — several times per frame, all but the last discarded.
+//
+// Values are absolute, so it's last-write-wins: a later `schedule` in the same
+// frame overwrites the pending value. `flush` commits the pending value now
+// (e.g. the gesture ended, so the resting position must be exact) and cancels
+// the frame; the pending frame is also canceled on unmount so a late commit
+// can't fire into a torn-down tree.
+export function useRafCommit(commit) {
+    const stableCommit = useEventCallback(commit);
+    const pendingRef = useRef(undefined);
+    useEffect(() => () => {
+        const pending = pendingRef.current;
+        if (pending) {
+            cancelAnimationFrame(pending.id);
+        }
+    }, []);
+    const schedule = useCallback((value) => {
+        const pending = pendingRef.current;
+        if (pending) {
+            pending.value = value;
+        }
+        else {
+            pendingRef.current = {
+                value,
+                id: requestAnimationFrame(() => {
+                    const cur = pendingRef.current;
+                    pendingRef.current = undefined;
+                    if (cur) {
+                        stableCommit(cur.value);
+                    }
+                }),
+            };
+        }
+    }, [stableCommit]);
+    const flush = useCallback(() => {
+        const pending = pendingRef.current;
+        if (pending) {
+            cancelAnimationFrame(pending.id);
+            pendingRef.current = undefined;
+            stableCommit(pending.value);
+        }
+    }, [stableCommit]);
+    return { schedule, flush };
+}

package/esm/util/useResizeDrag.d.ts

@@ -0,0 +1,91 @@
+import type React from 'react';
+/**
+ * A pointer drag along one axis, reported as a distance per animation frame.
+ *
+ * This is the whole gesture behind a resize handle with no opinion about how the
+ * handle looks. `ui/ResizeHandle` is this hook plus JBrowse's own 4px bar, and an
+ * app drawing its own divider spreads the returned props onto it. That is the
+ * per-track resize story for an embedder who mounts displays themselves: the
+ * track row is the host's box, so the bar has to be theirs, but the gesture and
+ * the two model calls are not.
+ *
+ * ```tsx
+ * const handleProps = useResizeDrag({
+ *   onDrag: distance => {
+ *     display.resizeHeight(distance)
+ *   },
+ *   onDragStart: () => {
+ *     track.setResizing(true)
+ *   },
+ *   onDragEnd: () => {
+ *     track.setResizing(false)
+ *   },
+ * })
+ * return (
+ *   <div
+ *     {...handleProps}
+ *     style={{ height: 4, cursor: 'row-resize', touchAction: 'none' }}
+ *   />
+ * )
+ * ```
+ *
+ * `touchAction: 'none'` is the caller's half of the deal: without it the browser
+ * claims a touch drag as a page scroll and the pointer stream never arrives.
+ * `usePanZoom` writes the same property itself and this cannot — that one is
+ * handed the element as a ref, while this returns props and never sees a node.
+ * It stays out of those props because a caller's own `style` would silently
+ * replace it.
+ *
+ * Three things a hand-rolled version gets wrong, none of which fails loudly:
+ *
+ * - **One commit per frame.** A pointermove stream (plus the browser's own
+ *   coalesced batches) outruns the frame rate, and each commit reruns whatever
+ *   the resize drives. Committing per event relayouts a pileup several times a
+ *   frame and throws all but the last away.
+ * - **The distance is measured from the last commit**, not from where the press
+ *   started, so a dropped intermediate position costs nothing and a drag that
+ *   runs into a clamp (`resizeHeight` stops at the display's minimum) does not
+ *   bank a debt the pointer has to pay back on the way out.
+ * - **`data-gesture-owner` rides in the props.** It is the marker ancestor
+ *   gestures test for (`closest('[data-gesture-owner]')`, in the LGV's own pan
+ *   and in `usePanZoom`) before starting a drag of their own, so without it
+ *   dragging a resize bar pans the view sideways instead. A `stopPropagation` is
+ *   not a substitute: those ancestors listen on *mouse* events while this runs
+ *   on *pointer* events, so there is no shared event to stop, and stopping the
+ *   mousedown would also cost focus-on-click, whose document-level listener
+ *   (`useFocusOnInteraction`) React's stopPropagation does block.
+ */
+export declare function useResizeDrag({ onDrag, onDragStart, onDragEnd, vertical, gain, }: {
+    /**
+     * How far the pointer has travelled since the last committed frame, in px —
+     * divided by `gain`, and whole.
+     */
+    onDrag: (distance: number) => void;
+    onDragStart?: () => void;
+    onDragEnd?: () => void;
+    /**
+     * A vertical divider, dragged left/right (so the distance comes off `clientX`).
+     * The default is a horizontal divider dragged up/down, which is a track
+     * resize.
+     */
+    vertical?: boolean;
+    /**
+     * How many px this handle's own position moves per px the dragged value
+     * changes. The default 1 is a divider that moves with what it sizes.
+     *
+     * It is more than 1 whenever the value is SHARED by several stacked copies and
+     * this handle sits below more than one of them: the second of three synteny
+     * ribbons, or the second group's coverage band in a grouped pileup, moves 2px
+     * for every 1px of height, so an undivided drag ran the bar away at twice the
+     * pointer's speed and slid it out from under the cursor. Divide by the number
+     * of copies at or above the handle and the bar stays put; the value then
+     * changes by a fraction of the drag, which is what sharing it means.
+     */
+    gain?: number;
+}): {
+    onPointerMove: (event: React.PointerEvent) => void;
+    onPointerUp: (event: React.PointerEvent) => void;
+    onPointerCancel: (event: React.PointerEvent) => void;
+    onPointerDown: (event: React.PointerEvent) => void;
+    'data-gesture-owner': string;
+};

package/esm/util/useResizeDrag.js

@@ -0,0 +1,105 @@
+import { useRef } from 'react';
+import { usePointerDrag } from './usePointerDrag.js';
+import { useRafCommit } from './useRafCommit.js';
+/**
+ * A pointer drag along one axis, reported as a distance per animation frame.
+ *
+ * This is the whole gesture behind a resize handle with no opinion about how the
+ * handle looks. `ui/ResizeHandle` is this hook plus JBrowse's own 4px bar, and an
+ * app drawing its own divider spreads the returned props onto it. That is the
+ * per-track resize story for an embedder who mounts displays themselves: the
+ * track row is the host's box, so the bar has to be theirs, but the gesture and
+ * the two model calls are not.
+ *
+ * ```tsx
+ * const handleProps = useResizeDrag({
+ *   onDrag: distance => {
+ *     display.resizeHeight(distance)
+ *   },
+ *   onDragStart: () => {
+ *     track.setResizing(true)
+ *   },
+ *   onDragEnd: () => {
+ *     track.setResizing(false)
+ *   },
+ * })
+ * return (
+ *   <div
+ *     {...handleProps}
+ *     style={{ height: 4, cursor: 'row-resize', touchAction: 'none' }}
+ *   />
+ * )
+ * ```
+ *
+ * `touchAction: 'none'` is the caller's half of the deal: without it the browser
+ * claims a touch drag as a page scroll and the pointer stream never arrives.
+ * `usePanZoom` writes the same property itself and this cannot — that one is
+ * handed the element as a ref, while this returns props and never sees a node.
+ * It stays out of those props because a caller's own `style` would silently
+ * replace it.
+ *
+ * Three things a hand-rolled version gets wrong, none of which fails loudly:
+ *
+ * - **One commit per frame.** A pointermove stream (plus the browser's own
+ *   coalesced batches) outruns the frame rate, and each commit reruns whatever
+ *   the resize drives. Committing per event relayouts a pileup several times a
+ *   frame and throws all but the last away.
+ * - **The distance is measured from the last commit**, not from where the press
+ *   started, so a dropped intermediate position costs nothing and a drag that
+ *   runs into a clamp (`resizeHeight` stops at the display's minimum) does not
+ *   bank a debt the pointer has to pay back on the way out.
+ * - **`data-gesture-owner` rides in the props.** It is the marker ancestor
+ *   gestures test for (`closest('[data-gesture-owner]')`, in the LGV's own pan
+ *   and in `usePanZoom`) before starting a drag of their own, so without it
+ *   dragging a resize bar pans the view sideways instead. A `stopPropagation` is
+ *   not a substitute: those ancestors listen on *mouse* events while this runs
+ *   on *pointer* events, so there is no shared event to stop, and stopping the
+ *   mousedown would also cost focus-on-click, whose document-level listener
+ *   (`useFocusOnInteraction`) React's stopPropagation does block.
+ */
+export function useResizeDrag({ onDrag, onDragStart, onDragEnd, vertical = false, gain = 1, }) {
+    const prevPosRef = useRef(0);
+    const getPos = (event) => vertical ? event.clientX : event.clientY;
+    // The scheduled value is the absolute pointer position, last-write-wins, and
+    // the delta against the previous commit is derived here.
+    //
+    // Whole px, and the remainder stays in the baseline rather than in a second
+    // ref: a divided delta has a sub-pixel tail, and every consumer rounds (a band
+    // height is whole px), so rounding it away each frame instead made a gain-2
+    // drag travel 4/3 of the pointer. Leaving the unspent fraction ahead of
+    // `prevPos` is the same mechanism that keeps a drag into a clamp from banking
+    // debt — the distance is always measured from what was last committed.
+    const { schedule, flush } = useRafCommit(pos => {
+        const distance = Math.trunc((pos - prevPosRef.current) / gain);
+        if (distance !== 0) {
+            prevPosRef.current += distance * gain;
+            onDrag(distance);
+        }
+    });
+    const handlers = usePointerDrag({
+        onDragStart: event => {
+            prevPosRef.current = getPos(event);
+            onDragStart?.();
+        },
+        onDrag: event => {
+            event.preventDefault();
+            // read the position synchronously: the deferred commit runs after React
+            // has nulled the event
+            schedule(getPos(event));
+        },
+        onDragEnd: () => {
+            // land the resting size exactly, rather than a frame late
+            flush();
+            onDragEnd?.();
+        },
+    });
+    return {
+        ...handlers,
+        onPointerDown: (event) => {
+            // stops the press from starting a text selection that follows the drag
+            event.preventDefault();
+            handlers.onPointerDown(event);
+        },
+        'data-gesture-owner': 'true',
+    };
+}

package/esm/util/useRowVirtualScroll.d.ts

@@ -0,0 +1,32 @@
+interface RowScrollTarget {
+    effectiveRowHeight: number;
+    scrollTop: number;
+    nrow: number;
+    scrollableHeight: number;
+    setRowHeight: (n: number) => void;
+    setScrollTop: (n: number) => void;
+}
+/**
+ * Wheel gestures over a **row-stack** panel — the multi-sample variant displays
+ * and MAF: `shift`+wheel resizes the rows (a vertical-zoom that keeps the row
+ * under the cursor put), a plain wheel scrolls them, and anything the panel
+ * can't consume is left to bubble to the view.
+ *
+ * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
+ * DOM overflow container, so nothing scrolls them without this.
+ *
+ * ADR-027 keeps wheel-*intent* dispatch per handler, because the four panels do
+ * not agree on what a gesture means — and that still holds. This is the one rule
+ * two of them genuinely share, which the ADR states outright ("same rule as the
+ * variant displays, and deliberately so: same sample-row shape, same coupled
+ * row-height axis"). It is unified for exactly that reason, and no further: the
+ * pileup / canvas-basic rule (`shift` scrolls, nothing resizes) stays where it
+ * is. `scrollZoom` and `viewportHeight` are inputs rather than reads off the
+ * model, so core needs no view typing and each display keeps naming its own
+ * rows-area height.
+ */
+export declare function useRowVirtualScroll(el: HTMLElement | null, model: RowScrollTarget, { viewportHeight, scrollZoom, }: {
+    viewportHeight: number;
+    scrollZoom: boolean;
+}): void;
+export {};