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

package/portal/portal-mount.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where a portal renders: a CSS selector (resolved in the browser; serializable, so it works on
+ * resumed pages), an element `ref()`, an element or a function returning one (browser-rendered
+ * portals only: elements and plain functions do not serialize).
+ */
+export type PortalMount = string | Element | null | undefined | (() => Element | null | undefined);
+/** Resolve a mount to an element (`document.body` when missing). */
+export declare function resolveMount(mount: PortalMount): Element;

package/portal/portal-mount.js

@@ -0,0 +1,7 @@
+// Portal mount resolution (browser only), kept out of the component module.
+/** Resolve a mount to an element (`document.body` when missing). */
+export function resolveMount(mount) {
+    const value = typeof mount === "function" ? mount() : mount;
+    const element = typeof value === "string" ? document.querySelector(value) : value;
+    return element ?? document.body;
+}

package/portal/portal-outlet.d.ts

@@ -0,0 +1,88 @@
+import { type Owner } from "@rivetjs/reactivity";
+/** Attached view returned by an outlet (Angular `ComponentRef` / `EmbeddedViewRef`). */
+export interface PortalViewRef<C = unknown> {
+    /** Root nodes rendered into the outlet. */
+    readonly rootNodes: Node[];
+    /** Context (TemplatePortal) or props (ComponentPortal) it was rendered with. */
+    readonly context: C | undefined;
+    /** Destroy the view (dispose its owner, remove its nodes). */
+    destroy(): void;
+    /** Run `fn` when the view is destroyed. */
+    onDestroy(fn: () => void): void;
+    readonly destroyed: boolean;
+}
+export declare const throwNullPortalError: () => never;
+export declare const throwPortalAlreadyAttachedError: () => never;
+export declare const throwPortalOutletAlreadyDisposedError: () => never;
+export declare const throwUnknownPortalTypeError: () => never;
+export declare const throwNullPortalOutletError: () => never;
+export declare const throwNoPortalAttachedError: () => never;
+/** Something a portal can be attached to. */
+export interface PortalOutlet {
+    attach(portal: Portal<unknown>): unknown;
+    detach(): unknown;
+    dispose(): void;
+    hasAttached(): boolean;
+}
+/** Content that can be attached to a `PortalOutlet`. */
+export declare abstract class Portal<T> {
+    private _attachedHost;
+    /** Attach to `host`. */
+    attach(host: PortalOutlet): T;
+    /** Detach from the host it is attached to. */
+    detach(): void;
+    /** Whether it is attached to a host. */
+    get isAttached(): boolean;
+    /** Set the host reference without attaching (outlets call this). */
+    setAttachedHost(host: PortalOutlet | null): void;
+}
+/** A component rendered into an outlet. `owner` (from `getOwner()`) keeps the caller's contexts. */
+export declare class ComponentPortal<P = Record<string, unknown>> extends Portal<PortalViewRef<P>> {
+    readonly component: (props: P) => unknown;
+    props: P | undefined;
+    owner: Owner | null | undefined;
+    constructor(component: (props: P) => unknown, props?: P, owner?: Owner | null);
+}
+/** A render function (Angular `TemplateRef`) rendered into an outlet with an optional context. */
+export declare class TemplatePortal<C = undefined> extends Portal<PortalViewRef<C>> {
+    readonly template: (context: C) => unknown;
+    context: C | undefined;
+    owner: Owner | null | undefined;
+    constructor(template: (context: C) => unknown, context?: C, owner?: Owner | null);
+    /** Attach, optionally with a different context. */
+    attach(host: PortalOutlet, context?: C | undefined): PortalViewRef<C>;
+    detach(): void;
+}
+/** An existing element moved into the outlet (and back to where it was on detach). */
+export declare class DomPortal<T extends Element = HTMLElement> extends Portal<T> {
+    readonly element: T;
+    constructor(element: T);
+}
+/** Outlet base: attach bookkeeping and the dispose function of the attached content. */
+export declare abstract class BasePortalOutlet implements PortalOutlet {
+    protected _attachedPortal: Portal<unknown> | null;
+    private _disposeFn;
+    private _isDisposed;
+    hasAttached(): boolean;
+    attach<P>(portal: ComponentPortal<P>): PortalViewRef<P>;
+    attach<C>(portal: TemplatePortal<C>): PortalViewRef<C>;
+    attach<T extends Element>(portal: DomPortal<T>): T;
+    attach(portal: Portal<unknown>): unknown;
+    abstract attachComponentPortal<P>(portal: ComponentPortal<P>): PortalViewRef<P>;
+    abstract attachTemplatePortal<C>(portal: TemplatePortal<C>): PortalViewRef<C>;
+    attachDomPortal: null | ((portal: DomPortal<Element>) => unknown);
+    detach(): void;
+    dispose(): void;
+    setDisposeFn(fn: () => void): void;
+    private _invokeDisposeFn;
+}
+/** An outlet rendering into an element (Angular `DomPortalOutlet`). Browser only. */
+export declare class DomPortalOutlet extends BasePortalOutlet {
+    readonly outletElement: Element;
+    constructor(outletElement: Element);
+    attachComponentPortal<P>(portal: ComponentPortal<P>): PortalViewRef<P>;
+    attachTemplatePortal<C>(portal: TemplatePortal<C>): PortalViewRef<C>;
+    attachDomPortal: (portal: DomPortal<Element>) => Element;
+    /** Detach and remove the outlet element. */
+    dispose(): void;
+}

package/portal/portal-outlet.js

@@ -0,0 +1,222 @@
+// Imperative portals and outlets (Angular CDK portal): a `Portal` is content that can be attached
+// to a `PortalOutlet` somewhere else in the document. `ComponentPortal` = a Rivet component + props,
+// `TemplatePortal` = a render function + context (Angular's TemplateRef), `DomPortal` = an existing
+// element moved into the outlet and back. `DomPortalOutlet` renders into an element with the
+// runtime's `mount`. Browser only (outlets render client-side); for server-visible content use the
+// `<Portal>` component (`@rivetjs/cdk/portal`).
+//
+// Ported from @angular/cdk/portal (portal.ts, dom-portal-outlet.ts, portal-errors.ts), MIT, © Google LLC.
+import { runWithOwner } from "@rivetjs/reactivity";
+import { mount } from "@rivetjs/runtime/dom";
+export const throwNullPortalError = () => {
+    throw Error("Must provide a portal to attach");
+};
+export const throwPortalAlreadyAttachedError = () => {
+    throw Error("Host already has a portal attached");
+};
+export const throwPortalOutletAlreadyDisposedError = () => {
+    throw Error("This PortalOutlet has already been disposed");
+};
+export const throwUnknownPortalTypeError = () => {
+    throw Error("Attempting to attach an unknown Portal type. BasePortalOutlet accepts either a ComponentPortal, a TemplatePortal or a DomPortal.");
+};
+export const throwNullPortalOutletError = () => {
+    throw Error("Attempting to attach a portal to a null PortalOutlet");
+};
+export const throwNoPortalAttachedError = () => {
+    throw Error("Attempting to detach a portal that is not attached to a host");
+};
+/** Content that can be attached to a `PortalOutlet`. */
+export class Portal {
+    _attachedHost = null;
+    /** Attach to `host`. */
+    attach(host) {
+        if (host == null)
+            throwNullPortalOutletError();
+        if (host.hasAttached())
+            throwPortalAlreadyAttachedError();
+        this._attachedHost = host;
+        return host.attach(this);
+    }
+    /** Detach from the host it is attached to. */
+    detach() {
+        const host = this._attachedHost;
+        if (host != null) {
+            this._attachedHost = null;
+            host.detach();
+        }
+        else
+            throwNoPortalAttachedError();
+    }
+    /** Whether it is attached to a host. */
+    get isAttached() {
+        return this._attachedHost != null;
+    }
+    /** Set the host reference without attaching (outlets call this). */
+    setAttachedHost(host) {
+        this._attachedHost = host;
+    }
+}
+/** A component rendered into an outlet. `owner` (from `getOwner()`) keeps the caller's contexts. */
+export class ComponentPortal extends Portal {
+    component;
+    props;
+    owner;
+    constructor(component, props, owner) {
+        super();
+        this.component = component;
+        this.props = props;
+        this.owner = owner;
+    }
+}
+/** A render function (Angular `TemplateRef`) rendered into an outlet with an optional context. */
+export class TemplatePortal extends Portal {
+    template;
+    context;
+    owner;
+    constructor(template, context, owner) {
+        super();
+        this.template = template;
+        this.context = context;
+        this.owner = owner;
+    }
+    /** Attach, optionally with a different context. */
+    attach(host, context = this.context) {
+        this.context = context;
+        return super.attach(host);
+    }
+    detach() {
+        this.context = undefined;
+        return super.detach();
+    }
+}
+/** An existing element moved into the outlet (and back to where it was on detach). */
+export class DomPortal extends Portal {
+    element;
+    constructor(element) {
+        super();
+        this.element = element;
+    }
+}
+/** Outlet base: attach bookkeeping and the dispose function of the attached content. */
+export class BasePortalOutlet {
+    _attachedPortal = null;
+    _disposeFn = null;
+    _isDisposed = false;
+    hasAttached() {
+        return !!this._attachedPortal;
+    }
+    attach(portal) {
+        if (!portal)
+            throwNullPortalError();
+        if (this.hasAttached())
+            throwPortalAlreadyAttachedError();
+        if (this._isDisposed)
+            throwPortalOutletAlreadyDisposedError();
+        if (portal instanceof ComponentPortal) {
+            this._attachedPortal = portal;
+            return this.attachComponentPortal(portal);
+        }
+        if (portal instanceof TemplatePortal) {
+            this._attachedPortal = portal;
+            return this.attachTemplatePortal(portal);
+        }
+        if (this.attachDomPortal && portal instanceof DomPortal) {
+            this._attachedPortal = portal;
+            return this.attachDomPortal(portal);
+        }
+        return throwUnknownPortalTypeError();
+    }
+    attachDomPortal = null;
+    detach() {
+        if (this._attachedPortal) {
+            this._attachedPortal.setAttachedHost(null);
+            this._attachedPortal = null;
+        }
+        this._invokeDisposeFn();
+    }
+    dispose() {
+        if (this.hasAttached())
+            this.detach();
+        this._invokeDisposeFn();
+        this._isDisposed = true;
+    }
+    setDisposeFn(fn) {
+        this._disposeFn = fn;
+    }
+    _invokeDisposeFn() {
+        if (this._disposeFn) {
+            this._disposeFn();
+            this._disposeFn = null;
+        }
+    }
+}
+/** Render `render()` into `outlet` (in `owner`, for contexts) and wrap it as a view. */
+function renderView(outlet, render, context, owner) {
+    const before = outlet.lastChild;
+    const stop = runWithOwner(owner ?? null, () => mount(render, outlet));
+    const rootNodes = [];
+    for (let node = before ? before.nextSibling : outlet.firstChild; node; node = node.nextSibling)
+        if (node.nodeType !== 8)
+            rootNodes.push(node);
+    const listeners = [];
+    let destroyed = false;
+    return {
+        rootNodes,
+        context,
+        get destroyed() {
+            return destroyed;
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            stop();
+            for (const fn of listeners.splice(0))
+                fn();
+        },
+        onDestroy(fn) {
+            listeners.push(fn);
+        },
+    };
+}
+/** An outlet rendering into an element (Angular `DomPortalOutlet`). Browser only. */
+export class DomPortalOutlet extends BasePortalOutlet {
+    outletElement;
+    constructor(outletElement) {
+        super();
+        this.outletElement = outletElement;
+    }
+    attachComponentPortal(portal) {
+        const view = renderView(this.outletElement, () => portal.component(portal.props ?? {}), portal.props, portal.owner);
+        this.setDisposeFn(() => view.destroy());
+        this._attachedPortal = portal;
+        return view;
+    }
+    attachTemplatePortal(portal) {
+        const view = renderView(this.outletElement, () => portal.template(portal.context), portal.context, portal.owner);
+        this.setDisposeFn(() => view.destroy());
+        this._attachedPortal = portal;
+        return view;
+    }
+    attachDomPortal = (portal) => {
+        const element = portal.element;
+        if (!element.parentNode)
+            throw Error("DOM portal content must be attached to a parent node.");
+        // Anchor at the element's previous position, to put it back on detach.
+        const anchorNode = this.outletElement.ownerDocument.createComment("dom-portal");
+        element.parentNode.insertBefore(anchorNode, element);
+        this.outletElement.appendChild(element);
+        this._attachedPortal = portal;
+        super.setDisposeFn(() => {
+            if (anchorNode.parentNode)
+                anchorNode.parentNode.replaceChild(element, anchorNode);
+        });
+        return element;
+    };
+    /** Detach and remove the outlet element. */
+    dispose() {
+        super.dispose();
+        this.outletElement.remove();
+    }
+}

package/preview-trigger/behaviour.d.ts

@@ -0,0 +1,70 @@
+import { type FocusableElement } from "../interactions/utils.js";
+import type { ElementSource } from "../overlay/position.js";
+import { type TooltipTriggerProps, type TooltipTriggerState } from "../state/tooltip.js";
+export interface AriaPreviewTriggerProps extends Omit<TooltipTriggerProps, "trigger" | "shouldCloseOnPress"> {
+}
+export interface AriaPreviewTriggerOptions extends AriaPreviewTriggerProps {
+    /** A ref to the trigger element (e.g. a Link). */
+    triggerRef: ElementSource<FocusableElement>;
+    /** A ref to the popover element. */
+    popoverRef: ElementSource<HTMLElement>;
+    /** Rivet: the popover id (RA: `useId()`), so the server and the browser agree. */
+    popoverId: string;
+}
+export interface PreviewTriggerTriggerAria {
+    /** Props for the trigger element (e.g. a Link). */
+    triggerProps: Record<string, unknown>;
+    /** Props for the popover overlay element. */
+    popoverProps: {
+        id: string;
+        onFocusWithin: () => void;
+        onBlurWithin: () => void;
+    };
+}
+/** Cancel a pending close and keep the preview open. */
+export declare function previewTriggerKeepOpen(state: TooltipTriggerState): void;
+/**
+ * Close the preview unless something is still keeping it open: the pointer is within the safe area, or
+ * focus is within the trigger or popover. During focus transitions the active element may briefly be
+ * the body; the popover's focusin handler re-opens in that case (focus moving in).
+ */
+export declare function previewTriggerCheckClose(state: TooltipTriggerState, options: Pick<AriaPreviewTriggerOptions, "triggerRef" | "popoverRef">): void;
+/** useHover `onHoverStart`. */
+export declare function previewTriggerHoverStart(state: TooltipTriggerState): void;
+/** useHover `onHoverEnd`. */
+export declare function previewTriggerHoverEnd(state: TooltipTriggerState): void;
+/** The trigger's `onPointerEnter` (useHover). */
+export declare function previewTriggerPointerEnter(e: PointerEvent, props: AriaPreviewTriggerProps, state: TooltipTriggerState): void;
+/** The trigger's `onPointerLeave` (useHover). */
+export declare function previewTriggerPointerLeave(e: PointerEvent, props: AriaPreviewTriggerProps, state: TooltipTriggerState): void;
+/** The trigger's `onFocus`. */
+export declare function previewTriggerFocus(e: FocusEvent, options: Pick<AriaPreviewTriggerOptions, "popoverRef" | "isDisabled">, state: TooltipTriggerState): void;
+/** The trigger's `onBlur`. */
+export declare function previewTriggerBlur(_e: FocusEvent, options: Pick<AriaPreviewTriggerOptions, "triggerRef" | "popoverRef">, state: TooltipTriggerState): void;
+/** The trigger's `on:rv-focus-scope-restore` (RA `react-aria-focus-scope-restore`): restore focus without reopening. */
+export declare function previewTriggerFocusScopeRestore(e: Event, state: TooltipTriggerState): void;
+/**
+ * The trigger's `onKeyDown`: move focus from the link into the preview when the user presses Tab while
+ * it is open (tabbing back out of the popover is handled by the popover's own FocusScope); Escape closes.
+ */
+export declare function previewTriggerKeyDown(e: KeyboardEvent, options: Pick<AriaPreviewTriggerOptions, "popoverRef">, state: TooltipTriggerState): void;
+/** useLongPress `onLongPress` (touch): open the preview and move focus into it once it opens. */
+export declare function previewTriggerLongPress(state: TooltipTriggerState): void;
+/**
+ * Rivet (delegated useLongPress `{ pointerType: "touch" }`): the wrapper's `onPointerDown` — a touch held
+ * for 500 ms opens the preview (no click / context menu after it), released earlier it does nothing.
+ */
+export declare function previewTriggerTouchStart(e: PointerEvent, props: AriaPreviewTriggerProps, state: TooltipTriggerState): void;
+/**
+ * RA's effects while open (call from the popover's client effect; returns the release): the safe area
+ * connecting the link and the popover keeps the preview open while the pointer moves between them (even
+ * diagonally, any placement, even with closeDelay 0); after a long press, focus moves to the popover.
+ */
+export declare function attachPreviewTrigger(state: TooltipTriggerState, options: AriaPreviewTriggerOptions): () => void;
+/**
+ * Provides the behavior and accessibility implementation for a preview trigger (React Aria
+ * `usePreviewTrigger`). The bag's closures are created in this `.tsx` module, so resumed bindings may
+ * capture them. Long press: wire
+ * `previewTriggerTouchStart` on the trigger's `onPointerDown`.
+ */
+export declare function previewTriggerProps(options: AriaPreviewTriggerOptions, state: TooltipTriggerState): PreviewTriggerTriggerAria;

package/preview-trigger/behaviour.jsx

@@ -0,0 +1,258 @@
+// Ported from @react-aria/tooltip (usePreviewTrigger.ts; react-aria/src/tooltip/usePreviewTrigger.ts), Apache-2.0, © Adobe.
+// A preview trigger displays a popover on hover, focus, or long press. Unlike a tooltip, the popover
+// may contain interactive content (React Aria `usePreviewTrigger` → `previewTriggerProps`).
+// Rivet:
+// - the hook's handlers are free functions over the serializable `TooltipTriggerState` (resumable:
+//   call them from inline arrows); the hook's refs (`ignoreFocus`, `shouldFocusOnOpen`,
+//   `pointerInSafeArea`) live in a browser-side WeakMap keyed by the state; `isFocusVisible` is read
+//   from the global modality at event time (RA keeps it in sync with `useFocusVisibleListener`).
+// - RA's effects become `attachPreviewTrigger(state, options)`: call while open (from the popover's
+//   client effect) — the safe area (`../overlay/safe-area.ts`) and the focus move after a long press.
+// - RA's `useEvent(triggerRef, 'react-aria-focus-scope-restore')` → `previewTriggerFocusScopeRestore`,
+//   the trigger's `on:rv-focus-scope-restore` handler (cdk FocusScope's restore event).
+// - `useHover` → `previewTriggerPointerEnter` / `Leave` (useHover semantics: mouse / pen only,
+//   emulated mouse after touch ignored); the touch long press is `previewTriggerTouchStart` (delegated
+//   RA useLongPress `{ pointerType: "touch" }`, threshold 500 ms) calling `previewTriggerLongPress`.
+// - `aria-expanded` / `aria-controls` / `aria-describedby` are accessors.
+// Deviation: `isDisabled` also stops keyboard focus from opening (upstream gates only hover / long press).
+import { untrack } from "@rivetjs/reactivity";
+import { focusWithoutScrolling, getActiveElement, getOwnerDocument, nodeContains, read as readValue } from "../interactions/utils.js";
+import { getInteractionModality, isFocusVisible, setInteractionModality, setupGlobalFocusEvents } from "../interactions/focus-visible.jsx";
+import { hoverPointerEnter, hoverPointerLeave } from "../interactions/hover.jsx";
+import { getFocusableTreeWalker } from "../focus/index.js";
+import { safeArea } from "../overlay/safe-area.js";
+import { closeTooltip, openTooltip } from "../state/tooltip.js";
+const refsByState = new WeakMap();
+const refsOf = (state) => {
+    let r = refsByState.get(state);
+    if (!r)
+        refsByState.set(state, (r = { ignoreFocus: false, shouldFocusOnOpen: false, longPress: null, pointerInSafeArea: false, hover: null }));
+    return r;
+};
+const read = (source) => (typeof source === "function" ? untrack(source) : source) ?? null;
+/** Cancel a pending close and keep the preview open. */
+export function previewTriggerKeepOpen(state) {
+    openTooltip(state, true);
+}
+/**
+ * Close the preview unless something is still keeping it open: the pointer is within the safe area, or
+ * focus is within the trigger or popover. During focus transitions the active element may briefly be
+ * the body; the popover's focusin handler re-opens in that case (focus moving in).
+ */
+export function previewTriggerCheckClose(state, options) {
+    const r = refsOf(state);
+    if (r.pointerInSafeArea)
+        return;
+    const trigger = read(options.triggerRef), popover = read(options.popoverRef);
+    const active = trigger ? getActiveElement(getOwnerDocument(trigger)) : null;
+    if (isFocusVisible() && ((trigger && nodeContains(trigger, active)) || (popover && nodeContains(popover, active))))
+        return;
+    closeTooltip(state);
+}
+/** useHover `onHoverStart`. */
+export function previewTriggerHoverStart(state) {
+    // Match useTooltipTrigger: only treat as hovered when the modality is actually a pointer.
+    if (getInteractionModality() === "pointer") {
+        refsOf(state).pointerInSafeArea = true;
+        openTooltip(state);
+    }
+}
+/** useHover `onHoverEnd`. */
+export function previewTriggerHoverEnd(state) {
+    // Before the preview opens, cancel a pending warmup if the pointer leaves the trigger. Once
+    // open, the safe-area polygon governs closing as the pointer moves to the popover.
+    if (!untrack(state.isOpen)) {
+        refsOf(state).pointerInSafeArea = false;
+        closeTooltip(state);
+    }
+}
+function hoverOf(state, isDisabled) {
+    const r = refsOf(state);
+    if (!r.hover)
+        r.hover = {
+            props: { isDisabled, onHoverStart: () => previewTriggerHoverStart(state), onHoverEnd: () => previewTriggerHoverEnd(state) },
+            state: { isHovered: false, pointerType: "", target: null, globals: [] },
+            hovered: { set: () => undefined },
+        };
+    return r.hover;
+}
+/** The trigger's `onPointerEnter` (useHover). */
+export function previewTriggerPointerEnter(e, props, state) {
+    // Resumed page: modality tracking installs on first use; the hover's own pointer event is the evidence.
+    setupGlobalFocusEvents(e.currentTarget);
+    if (getInteractionModality() === null && e.pointerType !== "touch")
+        setInteractionModality("pointer");
+    installTriggerListeners(e.currentTarget, props, state);
+    hoverPointerEnter(hoverOf(state, readValue(props.isDisabled)), e);
+}
+/** The trigger's `onPointerLeave` (useHover). */
+export function previewTriggerPointerLeave(e, props, state) {
+    hoverPointerLeave(hoverOf(state, readValue(props.isDisabled)), e);
+}
+/** The trigger's `onFocus`. */
+export function previewTriggerFocus(e, options, state) {
+    installTriggerListeners(e.currentTarget, options, state);
+    // Rivet: a disabled preview trigger never opens on focus either (RA usePreviewTrigger passes
+    // `isDisabled` only to useHover / useLongPress; useTooltipTrigger gates focus through useFocusable).
+    if (readValue(options.isDisabled))
+        return;
+    const r = refsOf(state);
+    if (r.ignoreFocus) {
+        r.ignoreFocus = false;
+        return;
+    }
+    const popover = read(options.popoverRef);
+    // Prevent browser focusing the link on long press when focus is already in the popover.
+    if (untrack(state.isOpen) && popover && e.relatedTarget === popover) {
+        focusWithoutScrolling(popover);
+        return;
+    }
+    if (isFocusVisible()) {
+        // Open after the warmup delay on keyboard focus, not immediately like a tooltip. This way
+        // tabbing quickly through the page doesn't open previews (and add their tab stops); the
+        // delay ensures the user is actually interested in the link's details.
+        openTooltip(state);
+    }
+}
+/** The trigger's `onBlur`. */
+export function previewTriggerBlur(_e, options, state) {
+    previewTriggerCheckClose(state, options);
+}
+/** The trigger's `on:rv-focus-scope-restore` (RA `react-aria-focus-scope-restore`): restore focus without reopening. */
+export function previewTriggerFocusScopeRestore(e, state) {
+    e.preventDefault();
+    refsOf(state).ignoreFocus = true;
+    e.currentTarget?.focus();
+}
+/**
+ * The trigger's `onKeyDown`: move focus from the link into the preview when the user presses Tab while
+ * it is open (tabbing back out of the popover is handled by the popover's own FocusScope); Escape closes.
+ */
+export function previewTriggerKeyDown(e, options, state) {
+    const popover = read(options.popoverRef);
+    if (e.key === "Tab" && !e.shiftKey && untrack(state.isOpen) && popover) {
+        const walker = getFocusableTreeWalker(popover, { tabbable: true });
+        const first = walker.nextNode();
+        if (first) {
+            e.preventDefault();
+            first.focus();
+        }
+    }
+    else if (e.key === "Escape") {
+        e.preventDefault();
+        closeTooltip(state, true);
+    }
+}
+/** useLongPress `onLongPress` (touch): open the preview and move focus into it once it opens. */
+export function previewTriggerLongPress(state) {
+    refsOf(state).shouldFocusOnOpen = true;
+    openTooltip(state, true);
+}
+const LONG_PRESS_THRESHOLD = 500;
+/**
+ * Rivet (delegated useLongPress `{ pointerType: "touch" }`): the wrapper's `onPointerDown` — a touch held
+ * for 500 ms opens the preview (no click / context menu after it), released earlier it does nothing.
+ */
+export function previewTriggerTouchStart(e, props, state) {
+    if (e.pointerType !== "touch" || readValue(props.isDisabled))
+        return;
+    const r = refsOf(state);
+    const target = e.target;
+    const win = target.ownerDocument;
+    const cancel = () => {
+        if (r.longPress)
+            clearTimeout(r.longPress);
+        r.longPress = null;
+        win.removeEventListener("pointerup", cancel, true);
+        win.removeEventListener("pointercancel", cancel, true);
+    };
+    cancel();
+    win.addEventListener("pointerup", cancel, true);
+    win.addEventListener("pointercancel", cancel, true);
+    r.longPress = setTimeout(() => {
+        cancel();
+        // No default click action (e.g. following a link) and no context menu after a long press.
+        const prevent = (event) => event.preventDefault();
+        target.addEventListener("click", prevent, { once: true });
+        target.addEventListener("contextmenu", prevent, { once: true });
+        setTimeout(() => {
+            target.removeEventListener("click", prevent);
+            target.removeEventListener("contextmenu", prevent);
+        }, 600);
+        previewTriggerLongPress(state);
+    }, LONG_PRESS_THRESHOLD);
+}
+const installed = new WeakSet();
+/**
+ * Rivet: listeners RA puts on the trigger element (`useEvent(triggerRef, 'react-aria-focus-scope-restore')`,
+ * useLongPress's pointerdown), installed once at its first pointerenter (touch fires it before
+ * pointerdown) or focus — nothing at load on a resumed page.
+ */
+function installTriggerListeners(trigger, props, state) {
+    if (!trigger || installed.has(trigger))
+        return;
+    installed.add(trigger);
+    trigger.addEventListener("rv-focus-scope-restore", (e) => previewTriggerFocusScopeRestore(e, state));
+    trigger.addEventListener("pointerdown", (e) => previewTriggerTouchStart(e, props, state));
+}
+/**
+ * RA's effects while open (call from the popover's client effect; returns the release): the safe area
+ * connecting the link and the popover keeps the preview open while the pointer moves between them (even
+ * diagonally, any placement, even with closeDelay 0); after a long press, focus moves to the popover.
+ */
+export function attachPreviewTrigger(state, options) {
+    const r = refsOf(state);
+    const popover = read(options.popoverRef);
+    if (popover && r.shouldFocusOnOpen) {
+        // When opened via long press, move focus to the popover itself so touch screen readers move
+        // their virtual cursor into the preview.
+        r.shouldFocusOnOpen = false;
+        focusWithoutScrolling(popover);
+    }
+    const release = safeArea({
+        triggerRef: options.triggerRef,
+        overlayRef: options.popoverRef,
+        isDisabled: readValue(options.isDisabled),
+        onSafeAreaChange: (isInSafeArea) => {
+            if (isInSafeArea === r.pointerInSafeArea)
+                return;
+            r.pointerInSafeArea = isInSafeArea;
+            if (isInSafeArea)
+                previewTriggerKeepOpen(state);
+            else
+                previewTriggerCheckClose(state, options);
+        },
+    });
+    return () => {
+        release();
+    };
+}
+/**
+ * Provides the behavior and accessibility implementation for a preview trigger (React Aria
+ * `usePreviewTrigger`). The bag's closures are created in this `.tsx` module, so resumed bindings may
+ * capture them. Long press: wire
+ * `previewTriggerTouchStart` on the trigger's `onPointerDown`.
+ */
+export function previewTriggerProps(options, state) {
+    const popoverId = options.popoverId;
+    return {
+        triggerProps: {
+            onFocus: (e) => previewTriggerFocus(e, options, state),
+            onBlur: (e) => previewTriggerBlur(e, options, state),
+            onKeyDown: (e) => previewTriggerKeyDown(e, options, state),
+            onPointerEnter: (e) => previewTriggerPointerEnter(e, options, state),
+            onPointerLeave: (e) => previewTriggerPointerLeave(e, options, state),
+            "on:rv-focus-scope-restore": (e) => previewTriggerFocusScopeRestore(e, state),
+            "aria-haspopup": "dialog",
+            "aria-expanded": () => state.isOpen(),
+            "aria-controls": () => (state.isOpen() ? popoverId : undefined),
+            "aria-describedby": () => (state.isOpen() ? popoverId : undefined),
+            style: { WebkitTouchCallout: "none", WebkitUserDrag: "none" },
+        },
+        popoverProps: {
+            id: popoverId,
+            onFocusWithin: () => previewTriggerKeepOpen(state),
+            onBlurWithin: () => previewTriggerCheckClose(state, options),
+        },
+    };
+}

package/preview-trigger/index.d.ts

@@ -0,0 +1,12 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import { type TooltipTriggerProps } from "../state/tooltip.js";
+export interface PreviewTriggerProps extends Omit<TooltipTriggerProps, "trigger" | "shouldCloseOnPress"> {
+    /** The delay time for the preview to show up (ms). @default 600 */
+    delay?: number;
+    /** The delay time for the preview to close (ms). @default 200 */
+    closeDelay?: number;
+    /** The trigger (e.g. a Link) and its `<Popover>`. */
+    children?: Content;
+}
+/** A PreviewTrigger displays a popover preview on hover, focus or long press of its trigger. */
+export declare function PreviewTrigger(props: PreviewTriggerProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;