@anyknown/axis 0.0.0-stage → 0.1.0

package/dist/axis.js

@@ -0,0 +1,655 @@
+import { isScrollKey, register } from "./coordinator.js";
+import { adjacentSnap, clamp, easeOutCubic, glideDuration, MIN_VELOCITY, momentumDistance, momentumStep, nearestSnap, parseSnapAlign, parseSnapType, snapPositions, toLogical, toPhysical, } from "./math.js";
+const AXES = ["x", "y"];
+const EDGE = 1;
+const WHEEL_SETTLE_MS = 150;
+const LINE_HEIGHT = 16;
+const DRAGGING_ATTR = "data-axis-dragging";
+const ZERO = { x: 0, y: 0 };
+const EMPTY_AXIS = {
+    scroll: 0,
+    maxScroll: 0,
+    progress: 0,
+    canScrollPrev: false,
+    canScrollNext: false,
+};
+const INITIAL_STATE = { x: EMPTY_AXIS, y: EMPTY_AXIS, isDragging: false, isMomentum: false };
+const DEFAULTS = { axis: "x", momentum: true, wheel: false, cursor: true };
+function merge(base, patch) {
+    const next = { ...base };
+    for (const key of Object.keys(DEFAULTS)) {
+        if (patch[key] !== undefined)
+            next[key] = patch[key];
+    }
+    return next;
+}
+function axisState(scroll, max, previous) {
+    const next = {
+        scroll,
+        maxScroll: max,
+        progress: max > 0 ? scroll / max : 0,
+        canScrollPrev: scroll > EDGE,
+        canScrollNext: scroll < max - EDGE,
+    };
+    for (const key of Object.keys(next))
+        if (next[key] !== previous[key])
+            return next;
+    return previous;
+}
+function px(value, basis) {
+    const number = Number.parseFloat(value);
+    if (Number.isNaN(number))
+        return 0;
+    return value.endsWith("%") ? (basis * number) / 100 : number;
+}
+/**
+ * Enhances a scroll container (`overflow: auto`) with mouse drag-scrolling, momentum, snap-aware release,
+ * optional wheel translation and an observable scroll state.
+ *
+ * Native scrolling stays the source of truth: touch, trackpad, keyboard and scrollbar input are untouched,
+ * and only a primary-button mouse drag is taken over (by writing `scrollLeft` / `scrollTop`). Nested instances
+ * share the drag: the innermost instance that can scroll in the drag's direction takes it.
+ */
+export function createAxis(el, options = {}) {
+    const win = el.ownerDocument.defaultView ?? window;
+    let opts = merge(DEFAULTS, options);
+    let state = INITIAL_STATE;
+    let destroyed = false;
+    const listeners = new Set();
+    const allows = (axis) => opts.axis === "both" || opts.axis === axis;
+    // --- inline style overrides -------------------------------------------------------------------------
+    const hadStyleAttr = el.hasAttribute("style");
+    // Safari only knows the prefixed property; Chrome aliases the two, so exactly one of them is used.
+    const USER_SELECT = "userSelect" in el.style ? "user-select" : "-webkit-user-select";
+    const saved = new Map();
+    // Watches the container (children, and class/style/dir anywhere inside it) and `dir` on every ancestor.
+    // The handler is defined with the rest of the wiring below.
+    const mutationObserver = new MutationObserver((records) => onMutations(records));
+    // axis's own inline styles do not change the layout. Their mutation records are dropped; records that
+    // were already pending are handed on as usual.
+    const ownStyle = (write) => {
+        const pending = mutationObserver.takeRecords();
+        write();
+        mutationObserver.takeRecords();
+        if (pending.length > 0)
+            queueMicrotask(() => onMutations(pending));
+    };
+    const override = (prop, value, important = false) => {
+        if (!saved.has(prop)) {
+            saved.set(prop, [el.style.getPropertyValue(prop), el.style.getPropertyPriority(prop)]);
+        }
+        else if (el.style.getPropertyValue(prop) === value)
+            return;
+        ownStyle(() => el.style.setProperty(prop, value, important ? "important" : ""));
+    };
+    const restore = (prop) => {
+        const original = saved.get(prop);
+        if (!original)
+            return;
+        saved.delete(prop);
+        ownStyle(() => {
+            if (original[0])
+                el.style.setProperty(prop, original[0], original[1]);
+            else
+                el.style.removeProperty(prop);
+        });
+    };
+    // --- geometry: everything below works in logical positions --------------------------------------------
+    // Cleared whenever the layout may have changed: resize and mutation observers, setOptions and refresh.
+    let snapCache = null;
+    const invalidate = () => {
+        snapCache = null;
+    };
+    const isRtl = () => win.getComputedStyle(el).direction === "rtl";
+    const maxScroll = () => ({
+        x: Math.max(0, el.scrollWidth - el.clientWidth),
+        y: Math.max(0, el.scrollHeight - el.clientHeight),
+    });
+    const read = (rtl = isRtl(), max = maxScroll()) => ({
+        x: clamp(toLogical(el.scrollLeft, rtl), 0, max.x),
+        y: clamp(el.scrollTop, 0, max.y),
+    });
+    const write = (position, rtl = isRtl()) => {
+        if (position.x !== undefined)
+            el.scrollLeft = toPhysical(position.x, rtl);
+        if (position.y !== undefined)
+            el.scrollTop = position.y;
+    };
+    const reducedMotion = () => win.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+    const measureSnaps = () => {
+        const style = win.getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+        const max = maxScroll();
+        const items = { x: [], y: [] };
+        for (const child of el.children) {
+            const childStyle = win.getComputedStyle(child);
+            const align = parseSnapAlign(childStyle.scrollSnapAlign);
+            if (align.x === "none" && align.y === "none")
+                continue;
+            const box = child.getBoundingClientRect();
+            const margin = (side) => px(childStyle.getPropertyValue(`scroll-margin-${side}`), 0);
+            const left = margin("left");
+            const top = margin("top");
+            items.x.push({ start: box.left - left, size: box.width + left + margin("right"), align: align.x });
+            items.y.push({ start: box.top - top, size: box.height + top + margin("bottom"), align: align.y });
+        }
+        const padding = (side, basis) => px(style.getPropertyValue(`scroll-padding-${side}`), basis);
+        return {
+            x: snapPositions({
+                start: rect.left + el.clientLeft,
+                size: el.clientWidth,
+                paddingStart: padding("left", el.clientWidth),
+                paddingEnd: padding("right", el.clientWidth),
+                scroll: el.scrollLeft,
+                maxScroll: max.x,
+                rtl: style.direction === "rtl",
+            }, items.x),
+            y: snapPositions({
+                start: rect.top + el.clientTop,
+                size: el.clientHeight,
+                paddingStart: padding("top", el.clientHeight),
+                paddingEnd: padding("bottom", el.clientHeight),
+                scroll: el.scrollTop,
+                maxScroll: max.y,
+                rtl: false,
+            }, items.y),
+        };
+    };
+    const snapPoints = () => (snapCache ??= measureSnaps());
+    // --- state --------------------------------------------------------------------------------------------
+    let motion = "idle";
+    const syncCursor = (max) => {
+        if (!opts.cursor)
+            restore("cursor");
+        else if (motion === "dragging")
+            override("cursor", "grabbing");
+        else if ((allows("x") && max.x > 0) || (allows("y") && max.y > 0))
+            override("cursor", "grab");
+        else
+            restore("cursor");
+    };
+    const update = () => {
+        if (destroyed)
+            return;
+        const max = maxScroll();
+        const position = read(isRtl(), max);
+        const x = axisState(position.x, max.x, state.x);
+        const y = axisState(position.y, max.y, state.y);
+        const isDragging = motion === "dragging";
+        const isMomentum = motion === "momentum";
+        syncCursor(max);
+        if (x === state.x &&
+            y === state.y &&
+            isDragging === state.isDragging &&
+            isMomentum === state.isMomentum) {
+            return;
+        }
+        state = { x, y, isDragging, isMomentum };
+        for (const listener of listeners)
+            listener(state);
+    };
+    const setMotion = (next) => {
+        motion = next;
+        update();
+    };
+    // --- motion: every lib-driven scroll runs with snap and smooth scrolling switched off inline -----------
+    let frame = 0;
+    let wheelTimer = 0;
+    let glideTarget = { x: 0, y: 0 };
+    // The computed scroll-snap-type from before the override, or null while nothing is overridden.
+    let snapType = null;
+    const beginOverride = () => {
+        if (snapType !== null)
+            return;
+        snapType = win.getComputedStyle(el).scrollSnapType;
+        override("scroll-snap-type", "none", true);
+        override("scroll-behavior", "auto", true);
+    };
+    const endOverride = () => {
+        if (snapType === null)
+            return;
+        snapType = null;
+        restore("scroll-snap-type");
+        restore("scroll-behavior");
+    };
+    const snapAxes = () => parseSnapType(snapType ?? win.getComputedStyle(el).scrollSnapType);
+    // While a drag lasts, the physical scroll position each instance under the pointer holds (see onScroll).
+    let held = null;
+    // True from yield() to pass() or interrupt(): another instance owns the drag and this one holds.
+    let yielded = false;
+    const stop = () => {
+        // Every scroll axis drives itself starts here, and it moves the position on purpose.
+        held = null;
+        if (frame)
+            win.cancelAnimationFrame(frame);
+        frame = 0;
+        win.clearTimeout(wheelTimer);
+        wheelTimer = 0;
+    };
+    const settle = () => {
+        stop();
+        // A glide that ends while another instance owns the drag holds where it ended.
+        if (yielded)
+            held = { x: el.scrollLeft, y: el.scrollTop };
+        endOverride();
+        setMotion("idle");
+    };
+    // Stops a glide, and lets go of a held position, when the user takes over with native input.
+    const interrupt = () => {
+        held = null;
+        yielded = false;
+        if (motion === "momentum" || motion === "glide")
+            settle();
+    };
+    const jump = (target) => {
+        stop();
+        beginOverride();
+        write(target);
+        settle();
+    };
+    // Glides both axes to `target` together. Axes missing from `target` stay where they are.
+    const animateTo = (target, velocity, kind) => {
+        stop();
+        const rtl = isRtl();
+        const from = read(rtl);
+        const moving = AXES.filter((axis) => target[axis] !== undefined && Math.abs(target[axis] - from[axis]) >= 0.5);
+        if (moving.length === 0 || reducedMotion()) {
+            jump(target);
+            return;
+        }
+        beginOverride();
+        glideTarget = { x: target.x ?? from.x, y: target.y ?? from.y };
+        const distance = { x: glideTarget.x - from.x, y: glideTarget.y - from.y };
+        const duration = Math.max(...moving.map((axis) => glideDuration(distance[axis], velocity[axis])));
+        const start = win.performance.now();
+        setMotion(kind);
+        // A listener may have destroyed the instance.
+        if (destroyed)
+            return;
+        const tick = (now) => {
+            if (destroyed)
+                return;
+            const eased = easeOutCubic(clamp((now - start) / duration, 0, 1));
+            const position = {};
+            for (const axis of moving)
+                position[axis] = from[axis] + distance[axis] * eased;
+            write(position, rtl);
+            if (eased < 1)
+                frame = win.requestAnimationFrame(tick);
+            else
+                settle();
+        };
+        frame = win.requestAnimationFrame(tick);
+    };
+    const runMomentum = (velocity) => {
+        stop();
+        beginOverride();
+        setMotion("momentum");
+        if (destroyed)
+            return;
+        const rtl = isRtl();
+        const max = maxScroll();
+        const position = read(rtl, max);
+        const speed = { ...velocity };
+        let last = win.performance.now();
+        const tick = (now) => {
+            if (destroyed)
+                return;
+            const dt = clamp(now - last, 0, 64);
+            last = now;
+            const next = {};
+            for (const axis of AXES) {
+                if (speed[axis] === 0)
+                    continue;
+                const advance = momentumStep(speed[axis], dt);
+                position[axis] = clamp(position[axis] + advance.distance, 0, max[axis]);
+                speed[axis] = position[axis] <= 0 || position[axis] >= max[axis] ? 0 : advance.velocity;
+                next[axis] = position[axis];
+            }
+            write(next, rtl);
+            if (Math.hypot(speed.x, speed.y) < MIN_VELOCITY)
+                settle();
+            else
+                frame = win.requestAnimationFrame(tick);
+        };
+        frame = win.requestAnimationFrame(tick);
+    };
+    // Called when a drag ends. `velocity` is the logical scroll velocity in px/ms.
+    const fling = (velocity) => {
+        const allowed = opts.momentum && !reducedMotion();
+        const speed = { x: allowed && allows("x") ? velocity.x : 0, y: allowed && allows("y") ? velocity.y : 0 };
+        const snaps = snapAxes();
+        if (snaps.x || snaps.y) {
+            // Predict where momentum would land, then glide each snapping axis to its nearest snap position.
+            const max = maxScroll();
+            const from = read(isRtl(), max);
+            const positions = snapPoints();
+            const target = {};
+            for (const axis of AXES) {
+                const landing = clamp(from[axis] + momentumDistance(speed[axis]), 0, max[axis]);
+                target[axis] = snaps[axis] ? nearestSnap(positions[axis], landing) : landing;
+            }
+            animateTo(target, speed, "momentum");
+        }
+        else if (Math.hypot(speed.x, speed.y) > MIN_VELOCITY)
+            runMomentum(speed);
+        else
+            settle();
+    };
+    // --- drag (the coordinator decides which instance owns it) ---------------------------------------------
+    let pointerId = -1;
+    let pressScroll = { x: 0, y: 0 };
+    const holdBack = () => {
+        if (!held)
+            return;
+        if (Math.abs(el.scrollLeft - held.x) >= 1)
+            el.scrollLeft = held.x;
+        if (Math.abs(el.scrollTop - held.y) >= 1)
+            el.scrollTop = held.y;
+    };
+    const endDrag = () => {
+        try {
+            if (el.hasPointerCapture(pointerId))
+                el.releasePointerCapture(pointerId);
+        }
+        catch {
+            // The pointer is already gone.
+        }
+        pointerId = -1;
+        el.removeAttribute(DRAGGING_ATTR);
+        restore(USER_SELECT);
+    };
+    const client = {
+        el,
+        onScrollbar(event) {
+            const rect = el.getBoundingClientRect();
+            const x = event.clientX - rect.left - el.clientLeft;
+            const y = event.clientY - rect.top - el.clientTop;
+            return x < 0 || y < 0 || x >= el.clientWidth || y >= el.clientHeight;
+        },
+        accepts(axis) {
+            if (!allows(axis))
+                return false;
+            const max = maxScroll();
+            return opts.axis === "both" ? max.x > 0 || max.y > 0 : max[axis] > 0;
+        },
+        canScroll(delta) {
+            const rtl = isRtl();
+            const max = maxScroll();
+            const position = read(rtl, max);
+            // The content moves with the pointer, so the scroll position moves against it.
+            const push = { x: toLogical(-delta.x, rtl), y: -delta.y };
+            return AXES.some((axis) => allows(axis) &&
+                ((push[axis] > 0 && position[axis] < max[axis] - EDGE) ||
+                    (push[axis] < 0 && position[axis] > EDGE)));
+        },
+        press() {
+            // A press freezes momentum (the glide after a drag, with its snap settling), like grabbing a flung
+            // list. Overrides stay on, so the browser cannot re-snap underneath. A glide the page started
+            // (scrollTo, prev/next, wheel snapping) keeps going; it only stops when this instance is dragged.
+            // Nothing is held yet: until the drag starts, the press may still be a click, and the page's own
+            // scrolling (scrollIntoView, focus, anchoring) must work.
+            if (motion === "momentum") {
+                stop();
+                setMotion("pressed");
+            }
+            else if (motion === "idle")
+                setMotion("pressed");
+        },
+        yield() {
+            yielded = true;
+            // A running glide drives the position itself, and holds where it ends (see settle).
+            if (motion === "glide" || motion === "wheel")
+                return;
+            held = { x: el.scrollLeft, y: el.scrollTop };
+        },
+        start(id) {
+            // Start from where the content is now: the page, a scrollTo or prev/next may have moved it during the
+            // press. Such a glide stops here, so it can neither fight the drag nor end it.
+            stop();
+            pressScroll = { x: el.scrollLeft, y: el.scrollTop };
+            held = { ...pressScroll };
+            pointerId = id;
+            beginOverride();
+            try {
+                el.setPointerCapture(id);
+            }
+            catch {
+                // Synthetic or already released pointer: the coordinator's window listeners still see it.
+            }
+            el.setAttribute(DRAGGING_ATTR, "");
+            override(USER_SELECT, "none");
+            win.getSelection()?.removeAllRanges();
+            setMotion("dragging");
+        },
+        move(delta) {
+            if (destroyed)
+                return;
+            if (allows("x")) {
+                el.scrollLeft = pressScroll.x - delta.x;
+                if (held)
+                    held.x = el.scrollLeft;
+            }
+            if (allows("y")) {
+                el.scrollTop = pressScroll.y - delta.y;
+                if (held)
+                    held.y = el.scrollTop;
+            }
+        },
+        pass() {
+            // Undo an autoscroll that came after the last scroll event, then let go.
+            holdBack();
+            held = null;
+            yielded = false;
+            // Only settle what the press froze. A glide that kept going during the press runs to its end.
+            if (motion !== "pressed")
+                return;
+            if (snapType !== null)
+                fling(ZERO);
+            else
+                setMotion("idle");
+        },
+        end(velocity) {
+            endDrag();
+            // Undo an autoscroll that came after the last scroll event, so the release starts where the drag is.
+            holdBack();
+            fling(velocity ? { x: toLogical(-velocity.x, isRtl()), y: -velocity.y } : ZERO);
+        },
+        interrupt,
+    };
+    // --- wheel (axis "x" only: vertical scrolling is already native) -------------------------------------
+    let wheelDirection = 1;
+    const settleWheel = () => {
+        wheelTimer = 0;
+        if (destroyed)
+            return;
+        if (!snapAxes().x) {
+            settle();
+            return;
+        }
+        // Like native wheel snapping: any wheel travel moves on to the next snap position in that direction.
+        const current = read().x;
+        const positions = snapPoints().x;
+        const target = adjacentSnap(positions, current - 2 * wheelDirection, wheelDirection) ?? nearestSnap(positions, current);
+        animateTo({ x: target }, ZERO, "glide");
+    };
+    const onWheel = (event) => {
+        if (opts.axis !== "x" || event.ctrlKey || event.shiftKey)
+            return;
+        if (Math.abs(event.deltaY) <= Math.abs(event.deltaX))
+            return;
+        if (motion === "pressed" || motion === "dragging")
+            return;
+        const scale = event.deltaMode === 1 ? LINE_HEIGHT : event.deltaMode === 2 ? el.clientWidth : 1;
+        const delta = event.deltaY * scale;
+        const rtl = isRtl();
+        const max = maxScroll();
+        const current = read(rtl, max).x;
+        // At the edge in the wheel's direction: let the page scroll.
+        if (delta > 0 ? current >= max.x - EDGE : current <= EDGE)
+            return;
+        event.preventDefault();
+        stop();
+        beginOverride();
+        wheelDirection = delta > 0 ? 1 : -1;
+        write({ x: clamp(current + delta, 0, max.x) }, rtl);
+        if (motion !== "wheel")
+            setMotion("wheel");
+        if (destroyed)
+            return;
+        wheelTimer = win.setTimeout(settleWheel, WHEEL_SETTLE_MS);
+    };
+    let wheelAttached = false;
+    const syncWheel = () => {
+        const wanted = opts.wheel && opts.axis === "x";
+        if (wanted === wheelAttached)
+            return;
+        wheelAttached = wanted;
+        if (wanted)
+            el.addEventListener("wheel", onWheel, { passive: false });
+        else
+            el.removeEventListener("wheel", onWheel);
+    };
+    // --- wiring -------------------------------------------------------------------------------------------
+    const resizeObserver = new ResizeObserver(() => {
+        invalidate();
+        update();
+    });
+    resizeObserver.observe(el);
+    for (const child of el.children)
+        resizeObserver.observe(child);
+    const onMutations = (records) => {
+        if (destroyed)
+            return;
+        invalidate();
+        // Records can arrive late and out of order (ownStyle defers some), so the current parent decides.
+        for (const record of records) {
+            if (record.target !== el)
+                continue;
+            for (const node of [...record.addedNodes, ...record.removedNodes]) {
+                if (node.nodeType !== 1)
+                    continue;
+                if (node.parentElement === el)
+                    resizeObserver.observe(node);
+                else
+                    resizeObserver.unobserve(node);
+            }
+        }
+        // Cheap when nothing changed (no notification), and it covers what the resize observer never reports,
+        // such as an added 0×0 child that only adds a flex gap.
+        update();
+    };
+    mutationObserver.observe(el, {
+        childList: true,
+        attributes: true,
+        attributeFilter: ["class", "style", "dir"],
+        subtree: true,
+    });
+    // A `dir` change on an ancestor flips the direction without resizing anything. Observing the root again
+    // would replace the options above when the container is the root itself.
+    const root = el.ownerDocument.documentElement;
+    if (el !== root) {
+        mutationObserver.observe(root, { attributes: true, attributeFilter: ["dir"], subtree: true });
+    }
+    const onKeyDown = (event) => {
+        if (isScrollKey(event))
+            interrupt();
+    };
+    const onScroll = () => {
+        // Safari autoscrolls the pressed containers towards a pointer held outside them, on any axis and also
+        // for instances that do not own the drag. Every instance under the press holds its position until the
+        // press ends or the user scrolls with the wheel or keyboard.
+        holdBack();
+        update();
+    };
+    const passive = { passive: true };
+    el.addEventListener("scroll", onScroll, passive);
+    el.addEventListener("wheel", interrupt, passive);
+    el.addEventListener("touchstart", interrupt, passive);
+    el.addEventListener("keydown", onKeyDown);
+    const unregister = register(client);
+    syncWheel();
+    update();
+    const resolveAxis = (method, axis) => {
+        if (axis)
+            return axis;
+        if (opts.axis === "both") {
+            throw new Error(`axis: ${method}() needs an axis ("x" or "y") when the instance uses axis: "both"`);
+        }
+        return opts.axis;
+    };
+    const step = (axis, direction) => {
+        if (destroyed || motion === "dragging")
+            return;
+        const visible = axis === "x" ? el.clientWidth : el.clientHeight;
+        // Repeated presses during a glide continue from where the glide is heading.
+        const max = maxScroll();
+        const from = motion === "glide" ? glideTarget[axis] : read(isRtl(), max)[axis];
+        const target = snapAxes()[axis]
+            ? (adjacentSnap(snapPoints()[axis], from, direction) ?? (direction === 1 ? max[axis] : 0))
+            : from + direction * visible * 0.9;
+        animateTo({ [axis]: clamp(target, 0, max[axis]) }, ZERO, "glide");
+    };
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        scrollPrev: (axis) => step(resolveAxis("scrollPrev", axis), -1),
+        scrollNext: (axis) => step(resolveAxis("scrollNext", axis), 1),
+        scrollTo(position, { animate = true } = {}) {
+            if (destroyed || motion === "dragging")
+                return;
+            const max = maxScroll();
+            const target = {};
+            for (const axis of AXES) {
+                const value = position[axis];
+                if (value !== undefined)
+                    target[axis] = clamp(value, 0, max[axis]);
+            }
+            if (animate)
+                animateTo(target, ZERO, "glide");
+            else
+                jump(target);
+        },
+        setOptions(patch) {
+            if (destroyed)
+                return;
+            opts = merge(opts, patch);
+            invalidate();
+            syncWheel();
+            update();
+        },
+        refresh() {
+            if (destroyed)
+                return;
+            invalidate();
+            update();
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            stop();
+            unregister();
+            if (pointerId !== -1)
+                endDrag();
+            resizeObserver.disconnect();
+            mutationObserver.disconnect();
+            el.removeEventListener("scroll", onScroll);
+            el.removeEventListener("wheel", interrupt);
+            el.removeEventListener("touchstart", interrupt);
+            el.removeEventListener("keydown", onKeyDown);
+            el.removeEventListener("wheel", onWheel);
+            el.removeAttribute(DRAGGING_ATTR);
+            for (const prop of saved.keys())
+                restore(prop);
+            if (!hadStyleAttr && !el.getAttribute("style"))
+                el.removeAttribute("style");
+            destroyed = true;
+            listeners.clear();
+        },
+    };
+}

package/dist/coordinator.d.ts

@@ -0,0 +1,36 @@
+import { type Vector } from "./math.js";
+/** True for a key press that scrolls: arrows, Page Up/Down, Home, End and Space, outside editable elements. */
+export declare function isScrollKey(event: KeyboardEvent): boolean;
+/** The side of an instance that the coordinator talks to. */
+export interface DragClient {
+    readonly el: HTMLElement;
+    /** True when the press lands on this element's own scrollbar, which belongs to the browser. */
+    onScrollbar(event: PointerEvent): boolean;
+    /** True when this instance drags along `axis` and has something to scroll. */
+    accepts(axis: "x" | "y"): boolean;
+    /** True when this instance can still scroll the way the pointer `delta` pushes it. */
+    canScroll(delta: Vector): boolean;
+    /** A drag may start here: stop any glide and remember the start position. */
+    press(): void;
+    /** The drag started and another instance under the pointer owns it: hold the current scroll position. */
+    yield(): void;
+    /** This instance owns the drag from now on, and holds its scroll position on the axes it does not drag. */
+    start(pointerId: number): void;
+    /** Pointer moved by `delta` since the press. */
+    move(delta: Vector): void;
+    /** The press ended and this instance did not own a drag: stop holding, settle what the press froze. */
+    pass(): void;
+    /** The drag ended. `velocity` is the pointer velocity in px/ms, or null when the drag was cancelled. */
+    end(velocity: Vector | null): void;
+    /** The user scrolls on purpose (wheel, keyboard), or non-draggable input arrived: stop gliding and holding. */
+    interrupt(): void;
+}
+/** Registers `client` with the coordinator of its window. Returns the function that unregisters it. */
+export declare function register(client: DragClient): () => void;
+/**
+ * Picks the owner for a drag that moved by `delta`. `chain` runs from the innermost instance outwards.
+ * First choice: the innermost instance that drags along the dominant axis and can still scroll that way.
+ * Otherwise the innermost one that drags along that axis at all (it is at its edge, but still owns the
+ * gesture so the click is not fired). Otherwise nobody, and the browser handles the movement natively.
+ */
+export declare function pickOwner(chain: readonly DragClient[], delta: Vector): DragClient | null;