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

package/popover/index.jsx

@@ -0,0 +1,285 @@
+// Ported from React Aria Components (Popover.tsx), Apache-2.0, © Adobe.
+// A popover is an overlay element positioned relative to a trigger. Trigger components (DialogTrigger,
+// MenuTrigger, Select, ComboBox, DatePicker, PreviewTrigger, SubmenuTrigger) feed it through
+// `PopoverContext` (`trigger` name, `triggerRef`, placement, …) and `OverlayTriggerStateContext`;
+// standalone it takes `triggerRef` + `isOpen` / `defaultOpen` / `onOpenChange`.
+// Rivet:
+// - renders in the div overlay layer (`<Overlay>`: portal + focus scope) while open or exiting; the
+//   presence sits in its own binding site (`span[data-rv-overlay-anchor]`, `display: contents`), so on a
+//   resumed page the first open re-creates only the popover, never the trigger.
+// - usePopover (`popoverProps`, ./use-popover.ts) runs from a client effect while open (released on
+//   close / unmount); positioning writes styles through CSSOM, `data-placement` on popover + arrow.
+// - enter / exit: `createEnterAnimation` / `createExitAnimation` (`@rivetjs/cdk/animation`), state on
+//   `data-entering` / `data-exiting` (`"true"`); render props are accessors (`placement()`, `isEntering()`).
+// - `class` (RAC `className`), default `rv-Popover`; `ref` is a Rivet ref.
+// - RAC's role detection runs in a client effect: role=dialog (and the id) once the element is mounted,
+//   unless a `[role=dialog]` is nested; the server renders RAC's initial state (dialog only for
+//   PreviewTrigger).
+// - collection build pass (`isHidden()`): children render directly (RAC `useIsHidden`).
+// Deviations: no `UNSTABLE_portalContainer` (PortalProvider only, decision 12); `render` (RAC DOMRenderProps) replaces the popover `<div>` (the underlay, `data-rv-overlay` marker and the JS-set stacking stay); no
+//   `runAfterKeyboard` defer of the reveal (the virtual keyboard tracker is lazy-loaded); focus
+//   containment is decided once when the popover renders (`!isNonModal || SubmenuTrigger`, never for
+//   PreviewTrigger) — RAC also contains when a nested Dialog calls `useOverlayFocusContain` inside a
+//   non-modal popover.
+import { read as readAccessor } from "../interactions/utils.js";
+import { createContext, effect, signal, untrack, useContext } from "@rivetjs/reactivity";
+import { Show, clientEffect, ref as createRef } from "@rivetjs/runtime/dom";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { Provider, contextProps, slottedContext, } from "../slots/index.jsx";
+import { createEnterAnimation, createExitAnimationState, watchExitAnimation } from "../utils/animation.jsx";
+import { dataBool } from "../utils/data-attrs.jsx";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { isFocusWithin } from "../utils/dom.js";
+import { focusSafely } from "../focus/index.js";
+import { getInteractionModality } from "../interactions/focus-visible.jsx";
+import { useLocale } from "../i18n/index.js";
+import { isHidden } from "../collections/components.jsx";
+import { slotProbing } from "#server";
+import { DismissButton } from "../overlay/dismiss-button.jsx";
+import { OverlayArrowContext, OverlayTriggerStateContext, PopoverContext } from "../overlay/contexts.js";
+import { Overlay } from "../portal/index.jsx";
+import { closeOverlay, createOverlayTriggerState } from "../state/overlays.js";
+import { popoverProps } from "./use-popover.js";
+import { isSlot, renderSlot } from "@rivetjs/runtime/slot";
+import { renderPropsOf } from "../slots/index.jsx";
+import { liveOptions } from "../utils/live.jsx";
+export { PopoverContext, OverlayTriggerStateContext };
+/** Stores a ref for the portal container for a group of popovers (e.g. submenus). */
+const PopoverGroupContext = resumableContext(createContext(null, { id: "rv-popover-group" }));
+const readBool = (value) => (typeof value === "function" ? value() : !!value);
+/** Context values may be accessors (e.g. DialogTrigger's `aria-labelledby`): read inside the binding. */
+const readValue = (value) => (typeof value === "function" ? value() : value);
+/** A popover is an overlay element positioned relative to a trigger. */
+export function Popover(props) {
+    // The trigger's ref (PopoverContext `ref`, e.g. ComboBox's popoverRef) is the element ref itself when it is a Rivet
+    // ref: RA mergeRefs assigns it at commit, before any child effect; a merged copy (`mergeRefValues`) would wait for
+    // a client effect — on a resumed page until idle — and a popover opened by a cold press would see it unset (ComboBox:
+    // the listbox's first virtual focus blurred the input "outside" the popover and closed it).
+    const contextRef = slottedContext(PopoverContext, props.slot)?.ref;
+    // A Rivet `ref()` (browser: a signal; server render: a `rivet.ref` cell function) — not a callback / `{ current }` ref.
+    const isRivetRef = typeof contextRef === "function" && (typeof contextRef.set === "function" || Symbol.for("rivet.ref") in contextRef);
+    const element = isRivetRef ? contextRef : createRef();
+    // RA mergeIds: a user id replaces the trigger's generated id, so the trigger's ARIA follows it.
+    const rawContext = useContext(PopoverContext);
+    if (rawContext?.idRef && props.id)
+        rawContext.idRef.set(props.id);
+    const [merged, mergedRef] = contextProps(props, element, PopoverContext);
+    const p = merged;
+    // The user's own ref receives the element too.
+    const ownRef = props.ref;
+    if (ownRef)
+        clientEffect(() => {
+            const el = element() ?? null;
+            untrack(() => {
+                if (typeof ownRef === "function") {
+                    const signalRef = ownRef;
+                    if (signalRef.set)
+                        signalRef.set(el ?? undefined);
+                    else
+                        ownRef(el);
+                }
+                else
+                    ownRef.current = el;
+            });
+        });
+    // If we are in a hidden tree, we still need to preserve our children.
+    if (isHidden()) {
+        // A field's server slot probe stops here: the popover's contexts are cleared in the real render (`probeSlots`).
+        if (slotProbing)
+            return null;
+        const children = p.children;
+        if (typeof children === "function" && !isSlot(children))
+            return children({
+                trigger: p.trigger || null,
+                placement: () => "bottom",
+                isEntering: () => false,
+                isExiting: () => false,
+                defaultChildren: null,
+            });
+        return renderSlot(children);
+    }
+    const contextState = useContext(OverlayTriggerStateContext);
+    const state = p.isOpen != null || p.defaultOpen != null || !contextState ? createOverlayTriggerState(liveOptions(p, [], ["isOpen"])) : contextState;
+    // Skip the automatic exit animation when closing instantly (e.g. swapping between previews during
+    // warmup). An explicitly provided isExiting prop still takes precedence.
+    // State here, its effect inside the branch (`watchExitAnimation` in PopoverInner): a closed popover records no
+    // client effect, so a resumed page with a closed Select / popover does not boot the runtime at load (tooltip: same).
+    const exit = createExitAnimationState(state.isOpen);
+    const explicitExiting = p.isExiting, skip = p.shouldSkipAnimation;
+    const isExiting = () => !!readAccessor(explicitExiting) || (!readBool(skip) && exit.isExiting());
+    const { direction } = useLocale();
+    const popoverRef = mergedRef;
+    return (<span data-rv-overlay-anchor="" style={{ display: "contents" }}>
+      <Show when={() => state.isOpen() || isExiting()}>
+        {() => <PopoverInner {...p} state={state} popoverRef={popoverRef} element={element} isExitingNow={isExiting} exit={exit} dir={direction}/>}
+      </Show>
+    </span>);
+}
+/** Global DOM props the popover sets itself. */
+const OWNED = ["style"];
+function PopoverInner(props) {
+    const { state, popoverRef, element, isExitingNow: isExiting, exit } = props;
+    watchExitAnimation(element, exit);
+    const arrowRef = createRef();
+    const containerRef = createRef();
+    const groupCtx = useContext(PopoverGroupContext);
+    const trigger = props.trigger;
+    const isSubPopover = !!groupCtx && trigger === "SubmenuTrigger";
+    const isNonModal = !!props.isNonModal;
+    const placement = signal(null);
+    const arrowOffset = signal(null);
+    const isOpen = signal(false);
+    // Skip the automatic entry animation when opening instantly (e.g. swapping between previews during
+    // warmup). An explicitly provided isEntering prop still takes precedence.
+    const enterAnimation = createEnterAnimation(element, () => !!placement() && isOpen());
+    const explicitEntering = props.isEntering, skip = props.shouldSkipAnimation;
+    const isEntering = () => !!readAccessor(explicitEntering) || (!readBool(skip) && enterAnimation());
+    const rp = renderPropsOf(props, {
+        defaultClassName: "rv-Popover",
+        values: { trigger: trigger || null, placement, isEntering, isExiting },
+    });
+    // Automatically render Popover with role=dialog except when isNonModal is true,
+    // or a dialog is already nested inside the popover.
+    const shouldBeDialog = !isNonModal || trigger === "SubmenuTrigger" || trigger === "PreviewTrigger";
+    const isDialog = signal(trigger === "PreviewTrigger");
+    // usePopover while open (released on close / unmount).
+    const options = {
+        triggerRef: props.triggerRef ?? null,
+        popoverRef: element,
+        arrowRef,
+        arrowStyle: false,
+        // If this is a submenu/subdialog, use the root popover's container to detect outside interaction and add aria-hidden.
+        groupRef: isSubPopover ? groupCtx : containerRef,
+        placement: props.placement ?? "bottom",
+        offset: props.offset ?? 8,
+        crossOffset: props.crossOffset,
+        containerPadding: props.containerPadding,
+        shouldFlip: props.shouldFlip,
+        maxHeight: props.maxHeight,
+        arrowBoundaryOffset: props.arrowBoundaryOffset,
+        boundaryElement: props.boundaryElement,
+        scroll: props.scroll,
+        shouldUpdatePosition: props.shouldUpdatePosition,
+        getTargetRect: props.getTargetRect,
+        isNonModal,
+        isKeyboardDismissDisabled: props.isKeyboardDismissDisabled,
+        shouldCloseOnInteractOutside: props.shouldCloseOnInteractOutside,
+        onFocusWithin: props.onFocusWithin,
+        onBlurWithin: props.onBlurWithin,
+        onFocusWithinChange: props.onFocusWithinChange,
+        trigger,
+    };
+    // Positioned once the Overlay's portal has moved the popover into the overlay layer (`onPlaced`): before that its
+    // host sits in place (a flex item next to the trigger: a gap shifts the trigger), the first position was off by
+    // that shift and the ResizeObserver re-positioned it inside its own callback ("ResizeObserver loop completed with
+    // undelivered notifications"). RA positions in a layout effect, after the portal rendered.
+    const placed = signal(false);
+    const triggerSource = options.triggerRef;
+    clientEffect(() => {
+        const el = element();
+        if (!el || !state.isOpen() || !placed())
+            return;
+        // RA positions in a layout effect once the trigger and the overlay both exist, in either order. On a resumed
+        // page the trigger's ref can bind after the popover opened (a cold press before the ref's client binding ran):
+        // track it, so the popover positions when it arrives instead of staying unpositioned.
+        if (typeof triggerSource === "function")
+            triggerSource();
+        return untrack(() => {
+            // RAC: overlayProps' zIndex is overridden by the render props' style.
+            const aria = popoverProps(rp.style()?.zIndex != null ? { ...options, zIndex: null } : options, state);
+            const stop = effect(() => {
+                placement.set(aria.placement());
+                const result = aria.position();
+                arrowOffset.set(result ? { left: result.arrowOffsetLeft, top: result.arrowOffsetTop } : null);
+            });
+            return () => {
+                stop();
+                aria.dispose();
+            };
+        });
+    });
+    // Since our trigger may open the OSK, RAC defers the reveal as a courtesy (here: right after mount).
+    clientEffect(() => {
+        if (element())
+            untrack(() => isOpen.set(true));
+    });
+    // Role detection, then focus the popover itself on mount, unless a child element is already focused.
+    // Skip this for submenus since hovering a submenutrigger should keep focus on the trigger.
+    clientEffect(() => {
+        const el = element();
+        if (!el)
+            return;
+        untrack(() => {
+            const dialog = shouldBeDialog && !el.querySelector("[role=dialog]");
+            isDialog.set(dialog);
+            if (dialog && trigger !== "PreviewTrigger" && (trigger !== "SubmenuTrigger" || getInteractionModality() !== "pointer") && !isFocusWithin(el)) {
+                // On a resumed page the `tabIndex` binding flushes after this effect: a div without tabindex is
+                // not focusable, so write it now (the binding writes the same value).
+                if (!el.hasAttribute("tabindex"))
+                    el.tabIndex = -1;
+                focusSafely(el);
+            }
+        });
+    });
+    // Read up front: an element with a spread is one binding, and it must not capture `props`.
+    const domProps = globalDOMProps(props, OWNED), id = props.id, ariaLabel = props["aria-label"], ariaLabelledBy = props["aria-labelledby"], slot = props.slot || undefined, dir = props.dir;
+    // RAC: the trigger's contexts (Label, Button, Input, … of a ComboBox) do not leak into the popover.
+    const clearContexts = (props.clearContexts ?? []);
+    const children = () => (<Provider values={[
+            [OverlayArrowContext, { placement, ref: arrowRef, offset: arrowOffset }],
+            [PopoverContext, null],
+            ...clearContexts.map((context) => [context, null]),
+        ]}>
+      {() => () => rp.children()}
+    </Provider>);
+    const overlay = () => {
+        if (props.render) {
+            const attrs = {
+                ...domProps,
+                class: () => rp.class(),
+                style: () => rp.style(),
+                id: () => (isDialog() ? id : undefined),
+                role: () => (isDialog() ? "dialog" : undefined),
+                tabindex: () => (isDialog() ? -1 : undefined),
+                "aria-label": () => readValue(ariaLabel),
+                "aria-labelledby": () => readValue(ariaLabelledBy),
+                ref: popoverRef,
+                slot,
+                dir,
+                "data-trigger": trigger,
+                "data-placement": () => placement() ?? undefined,
+                "data-entering": () => dataBool(isEntering()),
+                "data-exiting": () => dataBool(isExiting()),
+                "data-rv-overlay": "",
+                children: () => [
+                    !isNonModal ? <DismissButton onDismiss={() => closeOverlay(state)}/> : null,
+                    children(),
+                    <DismissButton onDismiss={() => closeOverlay(state)}/>,
+                ],
+            };
+            return props.render(attrs, { trigger: trigger || null, placement, isEntering, isExiting });
+        }
+        return (<div {...domProps} class={rp.class()} style={rp.style()} id={isDialog() ? id : undefined} role={isDialog() ? "dialog" : undefined} tabIndex={isDialog() ? -1 : undefined} aria-label={readValue(ariaLabel)} aria-labelledby={readValue(ariaLabelledBy)} ref={popoverRef} slot={slot} dir={dir} data-trigger={trigger} data-placement={placement() ?? undefined} data-entering={dataBool(isEntering())} data-exiting={dataBool(isExiting())} data-rv-overlay="">
+        {!isNonModal ? <DismissButton onDismiss={() => closeOverlay(state)}/> : null}
+        {children()}
+        <DismissButton onDismiss={() => closeOverlay(state)}/>
+      </div>);
+    };
+    const shouldContainFocus = shouldBeDialog && trigger !== "PreviewTrigger";
+    // Submenus/subdialogs are mounted into the root popover's container.
+    if (isSubPopover)
+        return (<Overlay shouldContainFocus={shouldContainFocus} portalContainer={groupCtx ?? undefined} onPlaced={() => placed.set(true)}>
+        {overlay()}
+      </Overlay>);
+    // A root popover renders an extra div to act as the portal container for submenus/subdialogs.
+    return (<Overlay shouldContainFocus={shouldContainFocus} onPlaced={() => placed.set(true)}>
+      {/* Own binding: reading `state.isOpen()` directly in the slot re-creates the whole overlay content on close (exit animation). */}
+      {() => !isNonModal && state.isOpen() ? (<div data-testid="underlay" data-rv-underlay="" onPointerDown={(event) => event.target === event.currentTarget && event.preventDefault()} style={{ position: "fixed", inset: "0" }}/>) : null}
+      <div ref={containerRef} style={{ display: "contents" }}>
+        <Provider values={[[PopoverGroupContext, containerRef]]}>{() => overlay()}</Provider>
+      </div>
+    </Overlay>);
+}
+export { PopoverOverlay } from "./popover-overlay.jsx";
+export * from "./use-popover.js";

package/popover/popover-overlay.d.ts

@@ -0,0 +1,27 @@
+import type { Content, Slot } from "@rivetjs/runtime/jsx-runtime";
+import { type TransitionClasses } from "@rivetjs/kit/transition";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type OverlayTriggerState } from "../state/overlays.js";
+import { type PopoverOverlayOptions } from "./behaviour.js";
+/** @internal */
+export interface PopoverOverlayProps extends Omit<PopoverOverlayOptions, "triggerId">, TransitionClasses, GlobalDOMAttributes<HTMLDivElement> {
+    id: string;
+    triggerId: string;
+    state: OverlayTriggerState;
+    /** Role of the popover element. `null`: none (menus, listboxes inside). @default 'dialog' */
+    role?: string | null;
+    class?: string;
+    /** Heading of the popover. */
+    title?: Content;
+    /** Run the enter transition when the popover is open on first render. */
+    appear?: boolean;
+    /** Called with the popover element when it opened (after usePopover attached). */
+    onOpened?: (element: HTMLElement) => void;
+    /** Extra attributes of the popover element. */
+    attributes?: Record<string, unknown>;
+    children?: Content | Slot<[{
+        close: () => void;
+    }]>;
+}
+/** @internal The popover part without a trigger (legacy shim for menu / select / date-picker). */
+export declare function PopoverOverlay(props: PopoverOverlayProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/popover/popover-overlay.jsx

@@ -0,0 +1,60 @@
+import { clientEffect } from "@rivetjs/runtime/dom";
+import { createTransition, TransitionPresence } from "@rivetjs/kit/transition";
+import { renderSlot } from "@rivetjs/runtime/slot";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { DismissButton } from "../overlay/dismiss-button.jsx";
+import { Overlay } from "../portal/index.jsx";
+import { closeOverlay } from "../state/overlays.js";
+import { attachPopoverOverlay } from "./behaviour.js";
+/** @internal The popover part without a trigger (legacy shim for menu / select / date-picker). */
+export function PopoverOverlay(props) {
+    const state = props.state;
+    const t = createTransition(state.isOpen, {
+        appear: props.appear,
+        enter: props.enter,
+        enterFrom: props.enterFrom,
+        enterTo: props.enterTo,
+        entered: props.entered,
+        leave: props.leave,
+        leaveFrom: props.leaveFrom,
+        leaveTo: props.leaveTo,
+        ariaComponents: true,
+    });
+    return <TransitionPresence transition={t}>{() => <PopoverOverlayContent {...props} t={t}/>}</TransitionPresence>;
+}
+function PopoverOverlayContent(props) {
+    const { id, state, t } = props;
+    const options = {
+        triggerId: props.triggerId,
+        placement: props.placement ?? "bottom",
+        offset: props.offset,
+        crossOffset: props.crossOffset,
+        containerPadding: props.containerPadding,
+        shouldFlip: props.shouldFlip,
+        maxHeight: props.maxHeight,
+        arrowBoundaryOffset: props.arrowBoundaryOffset,
+        boundaryId: props.boundaryId,
+        isNonModal: props.isNonModal,
+        isKeyboardDismissDisabled: props.isKeyboardDismissDisabled,
+        shouldCloseOnInteractOutside: props.shouldCloseOnInteractOutside,
+    };
+    const role = props.role === undefined ? "dialog" : props.role;
+    const isDialog = role === "dialog";
+    const hasTitle = props.title != null;
+    const children = props.children;
+    const onOpened = props.onOpened;
+    const isNonModal = !!props.isNonModal;
+    const domProps = globalDOMProps(props), attributes = props.attributes, className = props.class ?? "rv-Popover", labelledBy = role ? (hasTitle ? id + "-title" : props.triggerId) : undefined;
+    clientEffect(() => attachPopoverOverlay(t.ref(), state, options, isDialog, onOpened), { when: "load" });
+    return (<Overlay shouldContainFocus={!isNonModal}>
+      {!isNonModal && state.isOpen() ? <div data-testid="underlay" data-rv-underlay="" style={{ position: "fixed", inset: "0" }}/> : null}
+      <div {...domProps} {...attributes} id={id} class={t.className(className)} {...t.attributes()} ref={t.ref} role={role ?? undefined} tabIndex={role ? -1 : undefined} aria-labelledby={labelledBy} data-rv-overlay="">
+        {!isNonModal ? <DismissButton onDismiss={() => closeOverlay(state)}/> : null}
+        {hasTitle ? (<h2 id={id + "-title"} data-slot="title">
+            {props.title}
+          </h2>) : null}
+        {renderSlot(children, { close: () => closeOverlay(state) })}
+        <DismissButton onDismiss={() => closeOverlay(state)}/>
+      </div>
+    </Overlay>);
+}

package/popover/use-popover.d.ts

@@ -0,0 +1,57 @@
+import { type AriaPositionProps, type ElementSource, type PositionAria } from "../overlay/position.js";
+import { type FocusWithinProps } from "../interactions/focus.jsx";
+import { type OverlayTriggerState } from "../state/overlays.js";
+export interface AriaPopoverProps extends Omit<AriaPositionProps, "isOpen" | "onClose" | "target" | "overlay" | "arrow">, Omit<FocusWithinProps, "isDisabled"> {
+    /** The ref for the element which the popover positions itself with respect to. */
+    triggerRef: ElementSource;
+    /** The ref for the popover element. */
+    popoverRef: ElementSource<HTMLElement>;
+    /** A ref for the popover arrow element. */
+    arrowRef?: ElementSource;
+    /**
+     * An optional ref for a group of popovers, e.g. submenus.
+     * When provided, this element is used to detect outside interactions
+     * and hiding elements from assistive technologies instead of the popoverRef.
+     */
+    groupRef?: ElementSource;
+    /**
+     * Whether the popover is non-modal, i.e. elements outside the popover may be
+     * interacted with by assistive technologies.
+     *
+     * Most popovers should not use this option as it may negatively impact the screen
+     * reader experience. Only use with components such as combobox, which are designed
+     * to handle this situation carefully.
+     */
+    isNonModal?: boolean;
+    /**
+     * Whether pressing the escape key to close the popover should be disabled.
+     *
+     * Most popovers should not use this option. When set to true, an alternative
+     * way to close the popover with a keyboard must be provided.
+     *
+     * @default false
+     */
+    isKeyboardDismissDisabled?: boolean;
+    /**
+     * When user interacts with the argument element outside of the popover ref,
+     * return true if onClose should be called. This gives you a chance to filter
+     * out interaction with elements that should not dismiss the popover.
+     * By default, onClose will always be called on interaction outside the popover ref.
+     */
+    shouldCloseOnInteractOutside?: (element: Element) => boolean;
+    /** The name of the component that triggered the popover (RA reads `trigger === "SubmenuTrigger"`). */
+    trigger?: string;
+}
+export interface PopoverAria extends Pick<PositionAria, "placement" | "triggerAnchorPoint" | "position" | "updatePosition"> {
+    /** Props to apply to the underlay element, if any (its `onPointerDown`). */
+    underlayProps: {
+        onPointerDown: (event: PointerEvent) => void;
+    };
+    /** Release everything (call on close / unmount). */
+    dispose(): void;
+}
+/**
+ * Provides the behavior and accessibility implementation for a popover component. A popover is an
+ * overlay element positioned relative to a trigger (React Aria `usePopover`). Call on open.
+ */
+export declare function popoverProps(props: AriaPopoverProps, state: OverlayTriggerState): PopoverAria;

package/popover/use-popover.js

@@ -0,0 +1,92 @@
+// Ported from @react-aria/overlays (usePopover.ts), Apache-2.0, © Adobe.
+// Popover behaviour (React Aria `usePopover` → `popoverProps`): an overlay positioned relative to its
+// trigger — `overlay()` (Escape, close on outside interaction unless non-modal, close on blur),
+// `overlayPosition()` (flip, offsets, arrow, max height; non-modal popovers close when a scroll
+// parent of the trigger scrolls), document scroll lock and `inert` outside (modal popovers) or
+// `keepVisible` (non-modal), focus-within events on the popover.
+// Rivet:
+// - imperative: call it in the browser when the popover is open and rendered; it attaches the
+//   handlers RA spreads as `popoverProps` (overlay keydown / outside / blur, focusin / focusout of
+//   useFocusWithin) and the position styles (CSSOM) to the elements directly. Returns RA's result
+//   (`placement`, `triggerAnchorPoint` as signals, `underlayProps`) plus `updatePosition` and
+//   `dispose` (release on close / unmount; `<Popover>` does both from a client effect).
+// - refs are `ElementSource`s (an element, a `ref()` or an accessor).
+import { ariaHideOutside, keepVisible } from "../overlay/aria-hide-outside.js";
+import { overlay } from "../overlay/index.js";
+import { overlayPosition } from "../overlay/position.js";
+import { modalUnderlayPointerDown } from "../overlay/modal-overlay.js";
+import { preventScroll } from "../overlay/prevent-scroll.js";
+import { focusWithinBlur, focusWithinFocus } from "../interactions/focus.jsx";
+import { closeOverlay } from "../state/overlays.js";
+const read = (source) => (typeof source === "function" ? source() : source) ?? null;
+/**
+ * Provides the behavior and accessibility implementation for a popover component. A popover is an
+ * overlay element positioned relative to a trigger (React Aria `usePopover`). Call on open.
+ */
+export function popoverProps(props, state) {
+    const { triggerRef, popoverRef, groupRef, arrowRef, isNonModal, isKeyboardDismissDisabled, shouldCloseOnInteractOutside, onFocusWithin, onBlurWithin, onFocusWithinChange, trigger, ...otherProps } = props;
+    const element = read(popoverRef);
+    const groupElement = read(groupRef);
+    if (!element)
+        throw new Error("popoverProps(): missing popover element");
+    const isSubmenu = trigger === "SubmenuTrigger";
+    const cleanups = [];
+    cleanups.push(overlay(groupElement ?? element, {
+        isOpen: true,
+        onClose: () => closeOverlay(state),
+        shouldCloseOnBlur: true,
+        isDismissable: !isNonModal || isSubmenu,
+        isKeyboardDismissDisabled,
+        shouldCloseOnInteractOutside,
+        keyTarget: element,
+    }));
+    const point = state.point?.();
+    const position = overlayPosition({
+        ...otherProps,
+        target: triggerRef,
+        overlay: element,
+        arrow: arrowRef,
+        isOpen: true,
+        onClose: isNonModal && !isSubmenu ? () => closeOverlay(state) : null,
+        getTargetRect: otherProps.getTargetRect ?? (point ? () => new DOMRect(point.x, point.y, 0, 0) : undefined),
+    });
+    cleanups.push(() => position.dispose());
+    if (!isNonModal)
+        cleanups.push(preventScroll());
+    const undo = isNonModal ? keepVisible(groupElement ?? element) : ariaHideOutside([groupElement ?? element], { shouldUseInert: true });
+    if (undo)
+        cleanups.push(undo);
+    // useFocusWithin(props) merged into popoverProps.
+    if (onFocusWithin || onBlurWithin || onFocusWithinChange) {
+        const within = { props: { onFocusWithin, onBlurWithin, onFocusWithinChange }, state: { isFocusWithin: false, globals: [] } };
+        const onIn = (e) => focusWithinFocus(within, e);
+        const onOut = (e) => focusWithinBlur(within, e);
+        element.addEventListener("focusin", onIn);
+        element.addEventListener("focusout", onOut);
+        // Focus already inside (a popover that focused itself before this ran).
+        if (element.contains(element.ownerDocument.activeElement)) {
+            const active = element.ownerDocument.activeElement;
+            const event = new FocusEvent("focusin", { bubbles: true });
+            Object.defineProperty(event, "target", { value: active });
+            Object.defineProperty(event, "currentTarget", { value: element });
+            focusWithinFocus(within, event);
+        }
+        cleanups.push(() => {
+            element.removeEventListener("focusin", onIn);
+            element.removeEventListener("focusout", onOut);
+            for (const remove of within.state.globals.splice(0))
+                remove();
+        });
+    }
+    return {
+        placement: position.placement,
+        triggerAnchorPoint: position.triggerAnchorPoint,
+        position: position.position,
+        updatePosition: position.updatePosition,
+        underlayProps: { onPointerDown: modalUnderlayPointerDown },
+        dispose() {
+            for (const cleanup of cleanups.splice(0).reverse())
+                cleanup();
+        },
+    };
+}

package/portal/index.d.ts

@@ -0,0 +1,47 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import { resolveMount, type PortalMount } from "./portal-mount.js";
+export { resolveMount, type PortalMount };
+/** Default mount for portals below a `PortalProvider` (`null`: none). */
+export declare const PortalContext: import("@rivetjs/reactivity").Context<PortalMount>;
+/** Set the container of every `Portal` / `Overlay` / `OverlayContainer` rendered below it. */
+export declare function PortalProvider(props: {
+    container?: PortalMount;
+    children?: Content | (() => Content);
+}): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface PortalProps {
+    /** Where to render. @default the nearest PortalProvider's container, else document.body */
+    mount?: PortalMount;
+    /** Class of the host element. */
+    class?: string;
+    /**
+     * Rivet: called once the host is in its mount (the move runs in a client effect, after the content's own effects
+     * may have run). Content measuring its layout (popover positioning) waits for it.
+     */
+    onPlaced?: () => void;
+    children?: Content;
+}
+/**
+ * Render `children` at the end of `mount` (default `document.body`), inside a
+ * `<div data-rivet-portal>`. Server: rendered in place and moved at `load`.
+ */
+export declare function Portal(props: PortalProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface OverlayProps {
+    /** Container of the portal. @default the nearest PortalProvider's container, else document.body */
+    portalContainer?: PortalMount;
+    /** No focus containment / restoration (you implement both). */
+    disableFocusManagement?: boolean;
+    /** Keep Tab inside the overlay. React Aria turns this on for modal overlays (`useModalOverlay`). */
+    shouldContainFocus?: boolean;
+    /** Exit animation running: focus may leave. A value or an accessor (read when the scope mounts). */
+    isExiting?: boolean | (() => boolean | undefined);
+    /** Rivet: `Portal` `onPlaced` (the overlay is in its container). */
+    onPlaced?: () => void;
+    children?: Content;
+}
+/**
+ * React Aria `Overlay`: a `Portal` with a `FocusScope` — focus returns to the element focused before
+ * it rendered when it goes away, and with `shouldContainFocus` Tab stays inside. Its content is wrapped
+ * in a `ClearPressResponder` (RA): press props of the trigger's `PressResponder` (DialogTrigger, …) do
+ * not reach buttons inside the overlay.
+ */
+export declare function Overlay(props: OverlayProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/portal/index.jsx

@@ -0,0 +1,76 @@
+// Portals that render on the server. `<Portal>` renders its children inside an owned
+// `<div data-rivet-portal>`: in place in the server HTML (visible without JavaScript, indexable),
+// then moved to its mount (default `document.body`) — at `load` on a resumed page, right after
+// mounting when rendered in the browser. Its owner's cleanup removes it (a `<Show>` turning false,
+// a re-created region, a client navigation). Because the move is a resumable `clientEffect`, a portal
+// behind `<Show when>` works whether `when` starts true (server-rendered branch: moved at load) or
+// false (created in the browser). Server markers inside the host stay balanced, so resumption is
+// unaffected by the move.
+//
+// Also: `PortalProvider` (React Aria `UNSAFE_PortalProvider`: default container for portals below
+// it), `Overlay` (React Aria `Overlay`: a portal + focus containment / restoration).
+//
+// `PortalProvider`, `Overlay` ported from @react-aria/overlays (PortalProvider.tsx, Overlay.tsx),
+// Apache-2.0, © Adobe. Imperative portals / outlets (Angular CDK): ./portal-outlet.ts.
+import { createContext, useContext } from "@rivetjs/reactivity";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { clientEffect, ref, Provider } from "@rivetjs/runtime/dom";
+import { FocusScope } from "../focus/focus-scope.jsx";
+import { ClearPressResponder } from "../interactions/pressable.jsx";
+import { resolveMount } from "./portal-mount.js";
+import { renderSlot } from "@rivetjs/runtime/slot";
+export { resolveMount };
+/** Default mount for portals below a `PortalProvider` (`null`: none). */
+export const PortalContext = resumableContext(createContext(null, { id: "rv-portal" }));
+/** Set the container of every `Portal` / `Overlay` / `OverlayContainer` rendered below it. */
+export function PortalProvider(props) {
+    // Plain children are a lazy compiler slot rendered under the provider; function children work too.
+    const children = props.children;
+    return (<Provider token={PortalContext} value={props.container ?? null}>
+      {renderSlot(children)}
+    </Provider>);
+}
+/**
+ * Render `children` at the end of `mount` (default `document.body`), inside a
+ * `<div data-rivet-portal>`. Server: rendered in place and moved at `load`.
+ */
+export function Portal(props) {
+    const host = ref();
+    const mount = props.mount ?? useContext(PortalContext), onPlaced = props.onPlaced;
+    clientEffect(() => {
+        const element = host();
+        if (!element)
+            return;
+        const target = resolveMount(mount);
+        if (element.parentNode !== target) {
+            // Moving a node blurs focus inside it (content that focused itself on mount, e.g. a menu item).
+            const focused = element.ownerDocument.activeElement;
+            const inside = !!focused && element.contains(focused);
+            target.append(element);
+            if (inside && element.ownerDocument.activeElement !== focused)
+                focused.focus({ preventScroll: true });
+        }
+        onPlaced?.();
+        return () => element.remove();
+    }, { when: "load" });
+    return (<div data-rivet-portal="" class={props.class} ref={host}>
+      {props.children}
+    </div>);
+}
+/**
+ * React Aria `Overlay`: a `Portal` with a `FocusScope` — focus returns to the element focused before
+ * it rendered when it goes away, and with `shouldContainFocus` Tab stays inside. Its content is wrapped
+ * in a `ClearPressResponder` (RA): press props of the trigger's `PressResponder` (DialogTrigger, …) do
+ * not reach buttons inside the overlay.
+ */
+export function Overlay(props) {
+    const children = props.children, exiting = props.isExiting;
+    const isExiting = typeof exiting === "function" ? !!exiting() : !!exiting;
+    return (<Portal mount={props.portalContainer} onPlaced={props.onPlaced}>
+      <ClearPressResponder>
+        {props.disableFocusManagement ? (children) : (<FocusScope restoreFocus contain={!!props.shouldContainFocus && !isExiting}>
+            {children}
+          </FocusScope>)}
+      </ClearPressResponder>
+    </Portal>);
+}