@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.0

package/overlay/prevent-scroll-ios.js

@@ -0,0 +1,331 @@
+// iOS Safari part of `preventScroll()` (loaded lazily, only there or for `overrideFocus`). Even with
+// `overflow: hidden` Mobile Safari scrolls the page: with collapsed toolbars, when the keyboard
+// covers the viewport, when focusing an input (centers it), and with the keyboard's next / previous
+// buttons. So: prevent `touchmove` outside scrollable elements, `overscroll-behavior: contain` on
+// nested scrollers (a `<style>`, applied before touchstart as of iOS 26), and focus programmatically
+// without page scroll, scrolling only the scroll parents once the virtual keyboard settled.
+// Keyboard tracking starts on first use (React Aria starts it at import).
+//
+// Ported from @react-aria/overlays (usePreventScroll.ts) and @react-aria/utils (keyboard.tsx,
+// runAfterKeyboard.ts, getNonce.ts), Apache-2.0, © Adobe.
+import { isFocusable } from "../a11y/index.js";
+import { isAndroid, isWebKit } from "../platform/index.js";
+import { getScrollParent, isScrollable, setStyle } from "./prevent-scroll.js";
+const eventTarget = (event) => event.composedPath?.()[0] ?? event.target;
+/** The CSP nonce for injected `<style>`: `<meta property="csp-nonce">`, else the nonce of a page script. */
+export function getNonce(doc = document) {
+    const meta = doc.querySelector('meta[property="csp-nonce"], meta[name="csp-nonce"]')?.content;
+    return meta || (doc.querySelector("script[nonce]")?.nonce ?? undefined) || undefined;
+}
+/** iOS Safari scroll lock; returns the restore function. */
+export function preventScrollMobileWebKit() {
+    ensureKeyboardTracking();
+    let scrollable;
+    let allowTouchMove = false;
+    const onTouchStart = (e) => {
+        // Nearest scrollable element from the touched one.
+        const target = eventTarget(e);
+        scrollable = isScrollable(target, true) ? target : getScrollParent(target, true);
+        allowTouchMove = false;
+        // Selected text: let the visitor adjust the selection.
+        const selection = target.ownerDocument.defaultView.getSelection();
+        if (selection && !selection.isCollapsed && selection.containsNode(target, true))
+            allowTouchMove = true;
+        // Range inputs: let the visitor drag the slider.
+        if (e.composedPath().some((el) => el instanceof HTMLInputElement && el.type === "range"))
+            allowTouchMove = true;
+        // A focused input with a selected range: let the visitor drag the handles.
+        const field = target;
+        if ("selectionStart" in target &&
+            "selectionEnd" in target &&
+            field.selectionStart < field.selectionEnd &&
+            target.ownerDocument.activeElement === target)
+            allowTouchMove = true;
+    };
+    // Stop nested scrollers from chaining to the window at their ends (applied before touchstart).
+    const style = document.createElement("style");
+    const nonce = getNonce();
+    if (nonce)
+        style.nonce = nonce;
+    style.textContent = "@layer {\n  * {\n    overscroll-behavior: contain;\n  }\n}";
+    document.head.prepend(style);
+    const onTouchMove = (e) => {
+        // Pinch zoom, selections, sliders.
+        if (e.touches.length === 2 || allowTouchMove)
+            return;
+        // Scrolling the window.
+        if (!scrollable || scrollable === document.documentElement || scrollable === document.body) {
+            e.preventDefault();
+            return;
+        }
+        // overscroll-behavior does not stop chaining when the element does not overflow
+        // (https://bugs.webkit.org/show_bug.cgi?id=243452): neither axis overflowing → prevent.
+        if (scrollable.scrollHeight === scrollable.clientHeight && scrollable.scrollWidth === scrollable.clientWidth)
+            e.preventDefault();
+    };
+    const onBlur = (e) => {
+        const target = eventTarget(e);
+        const relatedTarget = e.relatedTarget;
+        if (relatedTarget && willOpenKeyboard(relatedTarget)) {
+            // Re-focus programmatically so the focus override performs the scroll.
+            relatedTarget.focus();
+        }
+        else if (!relatedTarget) {
+            // Keyboard "Done" moves focus to the body; refocusing the same input later fires no blur and
+            // Safari would scroll natively: move focus to the nearest focusable parent instead.
+            const focusable = target.parentElement?.closest("[tabindex]");
+            focusable?.focus({ preventScroll: true });
+        }
+    };
+    const restoreFocus = overrideFocus();
+    document.addEventListener("touchstart", onTouchStart, { passive: false, capture: true });
+    document.addEventListener("touchmove", onTouchMove, { passive: false, capture: true });
+    document.addEventListener("blur", onBlur, true);
+    return () => {
+        document.removeEventListener("touchstart", onTouchStart, true);
+        document.removeEventListener("touchmove", onTouchMove, true);
+        document.removeEventListener("blur", onBlur, true);
+        style.remove();
+        restoreFocus();
+    };
+}
+/** Patch `HTMLElement.prototype.focus`: focus without scrolling the page, then scroll only its scroll parents. */
+export function overrideFocus() {
+    ensureKeyboardTracking();
+    const focus = HTMLElement.prototype.focus;
+    Reflect.defineProperty(HTMLElement.prototype, "focus", {
+        configurable: true,
+        writable: true,
+        value: function (opts) {
+            focus.call(this, { ...opts, preventScroll: true });
+            if (!opts || !opts.preventScroll) {
+                const scroll = () => {
+                    if (document.activeElement === this)
+                        scrollIntoView(this);
+                };
+                runAfterKeyboard((isOpen) => (isOpen ? scroll() : runAfterKeyboardTransition(() => scroll())));
+            }
+        },
+    });
+    return () => {
+        Reflect.defineProperty(HTMLElement.prototype, "focus", { configurable: true, writable: true, value: focus });
+    };
+}
+function scrollIntoView(target) {
+    const root = document.scrollingElement || document.documentElement;
+    const visualViewport = window.visualViewport;
+    let nextTarget = target;
+    while (nextTarget && nextTarget !== root && nextTarget.isConnected) {
+        // Adjust the scroll parent if the target is not in view.
+        const scrollable = getScrollParent(nextTarget);
+        if (scrollable !== document.documentElement && scrollable !== document.body && scrollable !== nextTarget) {
+            const scrollableRect = scrollable.getBoundingClientRect();
+            const targetRect = nextTarget.getBoundingClientRect();
+            if (targetRect.top < scrollableRect.top || targetRect.bottom > scrollableRect.top + nextTarget.clientHeight) {
+                let bottom = scrollableRect.bottom;
+                if (visualViewport)
+                    bottom = Math.min(bottom, visualViewport.offsetTop + visualViewport.height);
+                // Center within the viewport, clamped to the scroll range.
+                const adjustment = targetRect.top - scrollableRect.top - ((bottom - scrollableRect.top) / 2 - targetRect.height / 2);
+                scrollable.scrollTo({
+                    top: Math.max(0, Math.min(scrollable.scrollHeight - scrollable.clientHeight, scrollable.scrollTop + adjustment)),
+                    behavior: "smooth",
+                });
+            }
+        }
+        nextTarget = scrollable.parentElement;
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Virtual keyboard tracking (keyboard.tsx, runAfterKeyboard.ts).
+const KEYBOARD_HEIGHT = 100;
+const KEYBOARD_TIMEOUT = 600;
+const state = {
+    isOpen: false,
+    screenWidth: 0,
+    screenHeight: 0,
+    screenAngle: 0,
+    screenTimeout: 0,
+    startTimeStamp: 0,
+    endTimeStamp: 0,
+    resizeTimeStamp: 0,
+    resizeTimeout: 0,
+};
+// Input types that open no software keyboard.
+const nonTextInputTypes = new Set(["checkbox", "radio", "range", "color", "file", "image", "button", "submit", "reset"]);
+let tracking = false;
+const metaValue = (name) => document.querySelector(`meta[name="${name}"]`)?.content;
+function getTouchScreen() {
+    // Undo scaling: layout coordinate space.
+    const screenWidth = Number(window.visualViewport?.width ?? window.innerWidth);
+    const screenHeight = Number(window.visualViewport?.height ?? window.innerHeight);
+    const visualScale = Number(window.visualViewport?.scale ?? 1);
+    return { width: screenWidth * visualScale, height: screenHeight * visualScale, angle: window.screen.orientation?.angle ?? 0 };
+}
+function onResizeStart(e) {
+    // Reschedule only when the timer gets close.
+    if (state.resizeTimeStamp <= e.timeStamp + 50) {
+        state.resizeTimeStamp = e.timeStamp + 150;
+        window.clearTimeout(state.resizeTimeout);
+        state.resizeTimeout = window.setTimeout(onResizeEnd, 150);
+    }
+}
+function onResizeEnd() {
+    // Overlaying keyboards do not change geometry.
+    if (isAndroid() && metaValue("viewport")?.includes("overlays-content"))
+        return;
+    const time = performance.now();
+    const screen = getTouchScreen();
+    const elapsed = time - state.startTimeStamp;
+    let delta = state.screenHeight - screen.height;
+    const rotation = state.screenAngle - screen.angle;
+    // An open keyboard that rotated along closes: the old width predicts the closing height.
+    if (Math.abs(rotation) % 180 && state.screenWidth - screen.height < KEYBOARD_HEIGHT) {
+        state.screenWidth = screen.width;
+        state.screenHeight = screen.height;
+        state.screenAngle = screen.angle;
+        delta = 0;
+    }
+    // A resize outside the capture window updates the screen (debounced: WebKit may resize before focus).
+    if (elapsed > KEYBOARD_TIMEOUT) {
+        window.clearTimeout(state.screenTimeout);
+        state.screenTimeout = window.setTimeout(() => {
+            const activeElement = document.hasFocus() ? document.activeElement : null;
+            const willKeyboardOpen = willOpenKeyboard(activeElement);
+            const next = getTouchScreen();
+            if (Math.abs(state.screenAngle - next.angle) % 180)
+                return;
+            if (state.isOpen && willKeyboardOpen)
+                return;
+            state.screenWidth = next.width;
+            state.screenHeight = next.height;
+            state.screenAngle = next.angle;
+            state.isOpen = false;
+        }, KEYBOARD_TIMEOUT);
+    }
+    // Otherwise an opening, when the height changed past the threshold.
+    if (elapsed <= KEYBOARD_TIMEOUT && delta >= KEYBOARD_HEIGHT)
+        state.endTimeStamp = time;
+    state.isOpen = delta >= KEYBOARD_HEIGHT;
+}
+function onOrientationChange() {
+    const screen = getTouchScreen();
+    const rotation = state.screenAngle - screen.angle;
+    // A screen estimate must exist before focus lands after a rotation.
+    if (Math.abs(rotation) % 180 && !state.isOpen) {
+        const width = state.screenWidth;
+        state.screenWidth = state.screenHeight;
+        state.screenHeight = width;
+    }
+    if (!state.isOpen)
+        state.screenAngle = screen.angle;
+}
+function onFocus(e) {
+    const willKeyboardOpen = willOpenKeyboard(eventTarget(e));
+    const time = performance.now();
+    const screen = getTouchScreen();
+    const delta = state.screenHeight - screen.height;
+    if (delta < KEYBOARD_HEIGHT && willKeyboardOpen) {
+        state.screenWidth = screen.width;
+        state.screenHeight = screen.height;
+        state.screenAngle = screen.angle;
+        state.startTimeStamp = time;
+    }
+    if (willKeyboardOpen)
+        window.clearTimeout(state.screenTimeout);
+    if (delta >= KEYBOARD_HEIGHT && willKeyboardOpen)
+        state.endTimeStamp = time;
+}
+function ensureKeyboardTracking() {
+    if (tracking || typeof window === "undefined")
+        return;
+    tracking = true;
+    const screen = getTouchScreen();
+    // WebKit fires a single event per resize.
+    window.visualViewport?.addEventListener("resize", isWebKit() ? onResizeEnd : onResizeStart);
+    window.screen.orientation?.addEventListener("change", onOrientationChange);
+    window.addEventListener("focus", onFocus, { capture: true, passive: true });
+    state.screenWidth = screen.width;
+    state.screenHeight = screen.height;
+    state.screenAngle = screen.angle;
+}
+/** Whether the device has a software keyboard (best effort). */
+export function supportsKeyboard() {
+    if (isAndroid() && metaValue("viewport")?.includes("overlays-content"))
+        return false;
+    if (state.isOpen)
+        return true;
+    if (!state.startTimeStamp)
+        return window.navigator.maxTouchPoints > 0;
+    if (state.endTimeStamp >= state.startTimeStamp)
+        return true;
+    return performance.now() - state.startTimeStamp <= KEYBOARD_TIMEOUT ? state.endTimeStamp > 0 || window.navigator.maxTouchPoints > 0 : false;
+}
+/** Whether focusing `target` opens the software keyboard. */
+export function willOpenKeyboard(target) {
+    if (!(target instanceof Element) || !isFocusable(target))
+        return false;
+    const isTextArea = target instanceof HTMLTextAreaElement;
+    const isEditable = target instanceof HTMLElement && target.isContentEditable;
+    const isTextInput = target instanceof HTMLInputElement && !nonTextInputTypes.has(target.type);
+    return isTextArea || isEditable || isTextInput;
+}
+export const isKeyboardOpen = () => state.isOpen;
+const WEBKIT_OPEN_DELAY = 200;
+const TRANSITION_FRAMETIME = 50;
+const TRANSITION_TIMEOUT = 600;
+let interval;
+const transitionCallbacks = new Set();
+const resizeCallbacks = new Set();
+function onTransitionFrame(wasOpenKeyboard, signal) {
+    const isOpenKeyboard = isKeyboardOpen();
+    // Resize callbacks: once layout changed, or out of time.
+    if (wasOpenKeyboard !== isOpenKeyboard || signal.aborted)
+        for (const callback of resizeCallbacks) {
+            callback(isOpenKeyboard);
+            resizeCallbacks.delete(callback);
+        }
+    // WebKit fires one resize at the start of the ~200 ms opening: restart and flush when it ends.
+    if (!wasOpenKeyboard && isOpenKeyboard && isWebKit() && !signal.aborted) {
+        window.clearInterval(interval);
+        interval = setupInterval(WEBKIT_OPEN_DELAY);
+        return;
+    }
+    if (wasOpenKeyboard !== isOpenKeyboard || signal.aborted)
+        for (const callback of transitionCallbacks) {
+            callback(isOpenKeyboard);
+            transitionCallbacks.delete(callback);
+        }
+    if (resizeCallbacks.size + transitionCallbacks.size <= 0 || signal.aborted) {
+        window.clearInterval(interval);
+        interval = undefined;
+    }
+}
+const setupInterval = (timeout = TRANSITION_TIMEOUT) => window.setInterval(onTransitionFrame, TRANSITION_FRAMETIME, isKeyboardOpen(), AbortSignal.timeout(timeout));
+function queue(fn, into, fireOnClose) {
+    // No keyboard: synchronously.
+    if (!supportsKeyboard())
+        return (fn(false), () => { });
+    // Two frames: does focus land on an input?
+    let frame = window.requestAnimationFrame(() => {
+        frame = window.requestAnimationFrame(() => {
+            const activeElement = document.hasFocus() ? document.activeElement : null;
+            const willKeyboardOpen = willOpenKeyboard(activeElement);
+            if (isKeyboardOpen() === willKeyboardOpen)
+                return fn(willKeyboardOpen);
+            // On close, at once: callers may assert the initial containing block.
+            if (fireOnClose && isKeyboardOpen() && !willKeyboardOpen)
+                return fn(willKeyboardOpen);
+            into.add(fn);
+            interval ??= setupInterval();
+        });
+    });
+    return () => {
+        window.cancelAnimationFrame(frame);
+        into.delete(fn);
+    };
+}
+/** Run `fn` once a keyboard transition can no longer affect layout (at most ~600 ms later). */
+export const runAfterKeyboard = (fn) => queue(fn, resizeCallbacks, true);
+/** Run `fn` once the software keyboard finished its transition (at most ~600 ms later). */
+export const runAfterKeyboardTransition = (fn) => queue(fn, transitionCallbacks, false);

package/overlay/prevent-scroll.d.ts

@@ -0,0 +1,18 @@
+export interface PreventScrollOptions {
+    /** No lock (returns a no-op). */
+    isDisabled?: boolean;
+    /** Patch `HTMLElement.prototype.focus` so programmatic focus does not scroll the page (React Aria `UNSTABLE_overrideFocus`). */
+    overrideFocus?: boolean;
+}
+/** Lock document scrolling; returns the release function (idempotent). */
+export declare function preventScroll(options?: PreventScrollOptions): () => void;
+/** Whether a scroll lock is active (React Aria checks `overflow: hidden` on the root for this). */
+export declare const isScrollPrevented: () => boolean;
+/** Set an inline style property; returns the function restoring the previous value. */
+export declare function setStyle(element: HTMLElement, property: string, value: string): () => void;
+/** Whether `node` scrolls (overflow auto / scroll; the root unless hidden); with `checkForOverflow`, only if its content overflows. */
+export declare function isScrollable(node: Element | null, checkForOverflow?: boolean): boolean;
+/** Nearest scrollable ancestor of `node` (not `node` itself), else the scrolling element. */
+export declare function getScrollParent(node: Element, checkForOverflow?: boolean): Element;
+/** Scrollable ancestors of `node`, nearest first (React Aria `getScrollParents`). */
+export declare function getScrollParents(node: Element, checkForOverflow?: boolean): Element[];

package/overlay/prevent-scroll.js

@@ -0,0 +1,122 @@
+// Scroll locking (React Aria `usePreventScroll`): `preventScroll()` stops the document from
+// scrolling while an overlay is open and returns the restore function. Reference counted: the page
+// style is restored when the last lock is released. Standard browsers: `overflow: hidden` on the
+// root plus `scrollbar-gutter: stable` (or padding) so content does not shift. iOS Safari, which
+// scrolls anyway: the touch / focus handling of React Aria, loaded lazily from
+// `./prevent-scroll-ios.ts` (nothing for other platforms). Modal overlays lock scrolling with it
+// while open.
+//
+// Ported from @react-aria/overlays (usePreventScroll.ts) and @react-aria/utils (isScrollable.ts,
+// getScrollParent.ts), Apache-2.0, © Adobe.
+import { isIOS, isWebKit } from "../platform/index.js";
+// Active locks; restore of the page style when the count returns to 0.
+let preventScrollCount = 0;
+let restore;
+/** Lock document scrolling; returns the release function (idempotent). */
+export function preventScroll(options = {}) {
+    const { isDisabled, overrideFocus } = options;
+    if (isDisabled || typeof document === "undefined")
+        return () => { };
+    preventScrollCount++;
+    if (preventScrollCount === 1) {
+        if (isIOS() && isWebKit()) {
+            // Mobile Safari: overflow first (so scrollIntoView logic sees the lock), the rest when loaded.
+            const restoreOverflow = setStyle(document.documentElement, "overflow", "hidden");
+            let restoreRest, released = false;
+            void import("./prevent-scroll-ios.js").then((ios) => {
+                if (!released)
+                    restoreRest = ios.preventScrollMobileWebKit();
+            });
+            restore = () => {
+                released = true;
+                restoreRest?.();
+                restoreOverflow();
+            };
+        }
+        else
+            restore = preventScrollStandard(overrideFocus);
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        preventScrollCount--;
+        if (preventScrollCount === 0)
+            restore?.();
+    };
+}
+/** Whether a scroll lock is active (React Aria checks `overflow: hidden` on the root for this). */
+export const isScrollPrevented = () => preventScrollCount > 0;
+// Most browsers: overflow hidden on the root, keep the scrollbar's space.
+function preventScrollStandard(overrideFocus) {
+    const root = document.documentElement;
+    const scrollbarWidth = window.innerWidth - root.clientWidth;
+    const restores = [];
+    if (scrollbarWidth > 0)
+        // scrollbar-gutter also keeps fixed-position elements from shifting.
+        restores.push("scrollbarGutter" in root.style ? setStyle(root, "scrollbar-gutter", "stable") : setStyle(root, "padding-right", `${scrollbarWidth}px`));
+    restores.push(setStyle(root, "overflow", "hidden"));
+    if (overrideFocus) {
+        let undo, released = false;
+        void import("./prevent-scroll-ios.js").then((ios) => {
+            if (!released)
+                undo = ios.overrideFocus();
+        });
+        restores.push(() => {
+            released = true;
+            undo?.();
+        });
+    }
+    return () => {
+        for (const fn of restores.reverse())
+            fn();
+    };
+}
+/** Set an inline style property; returns the function restoring the previous value. */
+export function setStyle(element, property, value) {
+    const style = element.style;
+    const previous = style.getPropertyValue(property), priority = style.getPropertyPriority(property);
+    style.setProperty(property, value);
+    return () => {
+        if (previous)
+            style.setProperty(property, previous, priority);
+        else
+            style.removeProperty(property);
+    };
+}
+/** Whether `node` scrolls (overflow auto / scroll; the root unless hidden); with `checkForOverflow`, only if its content overflows. */
+export function isScrollable(node, checkForOverflow) {
+    if (!node)
+        return false;
+    const style = window.getComputedStyle(node);
+    const root = document.scrollingElement || document.documentElement;
+    let scrollable = /(auto|scroll)/.test(style.overflow + style.overflowX + style.overflowY);
+    // The root has `visible` overflow by default but scrolls.
+    if (node === root && style.overflow !== "hidden")
+        scrollable = true;
+    if (scrollable && checkForOverflow)
+        scrollable = node.scrollHeight !== node.clientHeight || node.scrollWidth !== node.clientWidth;
+    return scrollable;
+}
+/** Nearest scrollable ancestor of `node` (not `node` itself), else the scrolling element. */
+export function getScrollParent(node, checkForOverflow) {
+    let scrollableNode = node;
+    if (isScrollable(scrollableNode, checkForOverflow))
+        scrollableNode = scrollableNode.parentElement;
+    while (scrollableNode && !isScrollable(scrollableNode, checkForOverflow))
+        scrollableNode = scrollableNode.parentElement;
+    return scrollableNode || document.scrollingElement || document.documentElement;
+}
+/** Scrollable ancestors of `node`, nearest first (React Aria `getScrollParents`). */
+export function getScrollParents(node, checkForOverflow) {
+    const parents = [];
+    const root = document.scrollingElement || document.documentElement;
+    let current = node;
+    do {
+        if (isScrollable(current, checkForOverflow))
+            parents.push(current);
+        current = current.parentElement;
+    } while (current && current !== root);
+    return parents;
+}

package/overlay/safe-area.d.ts

@@ -0,0 +1,28 @@
+import type { ElementSource } from "./position.js";
+interface Point {
+    x: number;
+    y: number;
+}
+export interface SafeAreaOptions {
+    /** Ref for the trigger element. */
+    triggerRef: ElementSource;
+    /** Ref for the overlay element. */
+    overlayRef: ElementSource;
+    /** Whether this feature is disabled. */
+    isDisabled?: boolean;
+    /**
+     * Called on pointer move (and when the pointer leaves the document) with whether the pointer is
+     * currently within the "safe area" — the trigger, the overlay, or the region between them. This
+     * lets an overlay stay open while the pointer travels from the trigger to the overlay, even
+     * diagonally and regardless of placement.
+     */
+    onSafeAreaChange: (isInSafeArea: boolean) => void;
+}
+/**
+ * Tracks whether the pointer is within a "safe area" connecting a trigger and its overlay, so the
+ * overlay can stay open while the pointer moves between them. Call while open; returns the release.
+ */
+export declare function safeArea(options: SafeAreaOptions): () => void;
+/** Whether `point` is in the trigger rect, the overlay rect or the convex hull of both (padded). */
+export declare function isPointInSafeArea(point: Point, triggerRect: DOMRect, overlayRect?: DOMRect): boolean;
+export {};

package/overlay/safe-area.js

@@ -0,0 +1,108 @@
+// Ported from @react-aria/tooltip (useSafeArea.ts; react-aria/src/tooltip/useSafeArea.ts), Apache-2.0, © Adobe.
+// Tracks whether the pointer is within a "safe area" connecting a trigger and its overlay, so the
+// overlay can stay open while the pointer moves between them (hover-opened overlays: PreviewTrigger).
+// The safe area is the union of the trigger rect, the overlay rect, and the convex hull connecting the
+// two (a polygon), which works for any placement of the overlay relative to the trigger, diagonal
+// moves and any gap (offset / arrow) between them.
+// Rivet:
+// - `useSafeArea(options)` (an effect while `isOpen`) → `safeArea(options)`: call when the overlay
+//   opens (browser only), it returns the release (call on close). `isOpen` is implied.
+// - refs are `ElementSource`s; `isPointInSafeArea` is exported for tests.
+import { getOwnerDocument, getOwnerWindow } from "../utils/dom.js";
+// A small amount of padding (in pixels) added around the trigger and overlay so the safe area is
+// slightly forgiving of sub-pixel jitter and the gap between the elements.
+const PADDING = 8;
+const read = (source) => (typeof source === "function" ? source() : source) ?? null;
+/**
+ * Tracks whether the pointer is within a "safe area" connecting a trigger and its overlay, so the
+ * overlay can stay open while the pointer moves between them. Call while open; returns the release.
+ */
+export function safeArea(options) {
+    const { triggerRef, overlayRef, isDisabled } = options;
+    const trigger = read(triggerRef);
+    if (isDisabled || !trigger)
+        return () => { };
+    const onPointerMove = (e) => {
+        if (e.pointerType === "touch")
+            return;
+        const point = { x: e.clientX, y: e.clientY };
+        const triggerRect = trigger.getBoundingClientRect();
+        const overlayRect = read(overlayRef)?.getBoundingClientRect();
+        options.onSafeAreaChange(isPointInSafeArea(point, triggerRect, overlayRect));
+    };
+    // If the pointer leaves the document entirely, it is no longer in the safe area.
+    const onPointerLeave = () => options.onSafeAreaChange(false);
+    const win = getOwnerWindow(trigger);
+    const doc = getOwnerDocument(trigger);
+    win.addEventListener("pointermove", onPointerMove);
+    doc.documentElement.addEventListener("pointerleave", onPointerLeave);
+    return () => {
+        win.removeEventListener("pointermove", onPointerMove);
+        doc.documentElement.removeEventListener("pointerleave", onPointerLeave);
+    };
+}
+/** Whether `point` is in the trigger rect, the overlay rect or the convex hull of both (padded). */
+export function isPointInSafeArea(point, triggerRect, overlayRect) {
+    if (rectContains(triggerRect, point))
+        return true;
+    if (!overlayRect)
+        return false;
+    if (rectContains(overlayRect, point))
+        return true;
+    // Otherwise, check whether the point is within the convex hull connecting the two rects.
+    const hull = convexHull([...rectCorners(triggerRect), ...rectCorners(overlayRect)]);
+    return hull.length >= 3 && isPointInPolygon(point, hull);
+}
+function rectContains(rect, point) {
+    return point.x >= rect.left - PADDING && point.x <= rect.right + PADDING && point.y >= rect.top - PADDING && point.y <= rect.bottom + PADDING;
+}
+function rectCorners(rect) {
+    const left = rect.left - PADDING;
+    const right = rect.right + PADDING;
+    const top = rect.top - PADDING;
+    const bottom = rect.bottom + PADDING;
+    return [
+        { x: left, y: top },
+        { x: right, y: top },
+        { x: right, y: bottom },
+        { x: left, y: bottom },
+    ];
+}
+// Computes the convex hull of a set of points using the monotone chain algorithm.
+function convexHull(points) {
+    const sorted = points.slice().sort((a, b) => a.x - b.x || a.y - b.y);
+    if (sorted.length < 3)
+        return sorted;
+    const cross = (o, a, b) => (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
+    const lower = [];
+    for (const p of sorted) {
+        while (lower.length >= 2 && cross(lower[lower.length - 2], lower[lower.length - 1], p) <= 0)
+            lower.pop();
+        lower.push(p);
+    }
+    const upper = [];
+    for (let i = sorted.length - 1; i >= 0; i--) {
+        const p = sorted[i];
+        while (upper.length >= 2 && cross(upper[upper.length - 2], upper[upper.length - 1], p) <= 0)
+            upper.pop();
+        upper.push(p);
+    }
+    lower.pop();
+    upper.pop();
+    return lower.concat(upper);
+}
+// Ray casting point-in-polygon test.
+function isPointInPolygon(point, polygon) {
+    const { x, y } = point;
+    let inside = false;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        const xi = polygon[i].x;
+        const yi = polygon[i].y;
+        const xj = polygon[j].x;
+        const yj = polygon[j].y;
+        const intersect = yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+        if (intersect)
+            inside = !inside;
+    }
+    return inside;
+}

package/overlay-arrow/index.d.ts

@@ -0,0 +1,23 @@
+import { type RenderProps, type RefValue, type ClassNameOrFunction, type StyleOrFunction } from "../slots/index.jsx";
+import { type DOMRenderProps } from "../utils/render.js";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { OverlayArrowContext, type OverlayArrowContextValue } from "../overlay/contexts.js";
+import type { PlacementAxis } from "../overlay/position.js";
+export { OverlayArrowContext, type OverlayArrowContextValue };
+export interface OverlayArrowRenderProps {
+    /** The placement of the overlay relative to the trigger. @selector [data-placement="left | right | top | bottom"] */
+    placement: () => PlacementAxis | null;
+}
+export interface OverlayArrowProps extends RenderProps<OverlayArrowRenderProps>, DOMRenderProps<"div", OverlayArrowRenderProps>, Omit<GlobalDOMAttributes<HTMLDivElement>, "style"> {
+    /** The CSS class for the element. A function may be provided to compute the class based on component state. @default 'rv-OverlayArrow' */
+    class?: ClassNameOrFunction<OverlayArrowRenderProps>;
+    /** The inline style for the element. A function may be provided to compute the style based on component state. */
+    style?: StyleOrFunction<OverlayArrowRenderProps>;
+    id?: string;
+    ref?: RefValue<HTMLDivElement>;
+}
+/**
+ * An OverlayArrow renders a custom arrow element relative to an overlay element such as a popover or
+ * tooltip such that it aligns with a trigger element.
+ */
+export declare function OverlayArrow(props: OverlayArrowProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;