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

package/modal/index.jsx

@@ -0,0 +1,359 @@
+// Ported from packages/react-aria-components/src/Modal.tsx (ModalOverlay, Modal, ModalContext), Apache-2.0, © Adobe.
+// RAC DOM: `<ModalOverlay>` = the underlay `div.rv-ModalOverlay` in the overlay layer (`<Overlay>`:
+// a portal with a focus scope), `<Modal>` = the modal `div.rv-Modal` inside it, the `<Dialog>`
+// (`../dialog`) inside that. A `<Modal>` without a `<ModalOverlay>` wraps itself in one.
+// Rivet:
+// - presence: a `<Show>` while `state.isOpen() || isExiting()` (RAC returns null), wrapped in an own
+//   binding site (`span[data-rv-overlay-anchor]`, `display: contents`, rendered in place): on a resumed
+//   page the first open / close re-creates only the overlay, from serializable locals (context values
+//   are resolved in the outer component and passed down as props).
+// - enter / exit: `../utils/animation.tsx` (RA useEnterAnimation / useExitAnimation) → `data-entering` /
+//   `data-exiting="true"`; `onEnter` / `onExit` promises; `isEntering` / `isExiting` props accept an
+//   accessor too (a Signal: the component runs once, RAC re-renders).
+// - useModalOverlay → `modalOverlay(modalElement, props, state)` from a client effect while open
+//   (Escape, outside interaction, scroll lock, `inert` outside; `isEntering` → keepVisible) +
+//   `modalUnderlayPointerDown` on the underlay.
+// - `--visual-viewport-width/height`, `--page-width/height` are set once measured in the browser (the
+//   server HTML of an open modal has none: React Aria never server-renders a modal).
+// - the underlay keeps inline `position: fixed; inset: 0; z-index: 100` (behaviour styles, cdk rule).
+// - the PortalProvider container is resolved in the outer component (`useContext(PortalContext)`) and
+//   handed to `<Overlay>` (re-created overlays have no provider chain).
+// Deviations: `UNSTABLE_portalContainer` deleted (PortalProvider only, decision 12); `render` (RAC DOMRenderProps) replaces the ModalOverlay and Modal `<div>`s (inline stacking, `data-rv-overlay` and the underlay pointer-down stay);
+// the keyboard-deferred reveal (`runAfterKeyboard(() => setIsOpen(true))`) reveals on the first client
+// effect (the iOS keyboard module stays lazy).
+import { computed, createContext, signal, untrack, useContext } from "@rivetjs/reactivity";
+import { Show, clientEffect, ref as createRef } from "@rivetjs/runtime/dom";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { dataBool } from "../utils/data-attrs.jsx";
+import { hasLive, liveOmit, liveOptions } from "../utils/live.jsx";
+import { liveRenderProps } from "../slots/index.jsx";
+import { splitProps } from "@rivetjs/runtime/props";
+import { read } from "../interactions/utils.js";
+import { isScrollable, viewportSize } from "../utils/dom.js";
+import { createEnterAnimation, createExitAnimationState, watchExitAnimation } from "../utils/animation.jsx";
+import { overlayPresence } from "@rivetjs/kit/transition";
+import { DismissButton } from "../overlay/dismiss-button.jsx";
+import { modalOverlay, modalUnderlayPointerDown } from "../overlay/modal-overlay.js";
+import { OverlayTriggerStateContext } from "../overlay/contexts.js";
+import { PressResponderContext } from "../interactions/press.jsx";
+import { Overlay, PortalContext } from "../portal/index.jsx";
+import { closeOverlay, createOverlayTriggerState, setOpen } from "../state/overlays.js";
+import { Provider, contextProps, mergeRefValues, renderProps, resumableContext, } from "../slots/index.jsx";
+import { DialogContext } from "../dialog/contexts.js";
+/** Props for the nearest `<ModalOverlay>` / `<Modal>` from a parent (RAC `ModalContext`). */
+export const ModalContext = resumableContext(createContext(null, { id: "rv-modal-props" }));
+/** @private What a ModalOverlay passes to its Modal (RAC `InternalModalContext`). */
+export const InternalModalContext = resumableContext(createContext(null, { id: "rv-modal-internal" }));
+/**
+ * Opt-in work per open (a styled layer registers it, e.g. @rivetjs/ui's overlays: the motion token): `open(overlay,
+ * modal)` runs once per open, the overlay in the document. Unset (cdk alone): nothing runs, nothing ships.
+ */
+export const modalHooks = {};
+/** The motion token (`--rv-motion-spring` → inline spring timing; motion spec D17) for `modalHooks.open`. */
+export { applyMotionToken } from "../utils/motion-token.js";
+/** Motion presence per open-state owner (`modalExit`), see `ModalOverlayPresence`. */
+const presences = new WeakMap();
+/** A modal is an overlay element which blocks interaction with elements outside it (RAC `Modal`). */
+export function Modal(props) {
+    const ctx = useContext(InternalModalContext);
+    if (ctx) {
+        if (isDev() && (props.onOpenChange || props.defaultOpen !== undefined || props.isOpen !== undefined)) {
+            // create a list of props that are passed in but not allowed when using an external ModalOverlay
+            const invalidSet = new Set([
+                "isDismissable",
+                "isKeyboardDismissDisabled",
+                "isOpen",
+                "defaultOpen",
+                "onOpenChange",
+                "isEntering",
+                "isExiting",
+                "shouldCloseOnInteractOutside",
+            ]);
+            const invalidProps = Object.keys(props).filter((key) => invalidSet.has(key));
+            console.warn(`This modal is already wrapped in a ModalOverlay, props [${invalidProps.join(", ")}] should be placed on the ModalOverlay instead.`);
+        }
+        return <ModalContent props={props} ctx={ctx}/>;
+    }
+    if (hasLive(props)) {
+        // Live props (P5): the overlay keys forward unread (controlled `isOpen` / dismiss flags become accessors), the rest
+        // goes to the modal element unread.
+        const overlay = liveOptions(splitProps(props, OVERLAY_KEYS)[0], LIVE_KEYS, ["isOpen"]);
+        return resolveOverlay(overlay, undefined, liveOmit(props, OVERLAY_KEYS));
+    }
+    const { isDismissable, isKeyboardDismissDisabled, isOpen, defaultOpen, onOpenChange, isEntering, isExiting, shouldCloseOnInteractOutside, UNSTABLE_deferUntilEntered, UNSTABLE_overrideFocus, ...otherProps } = props;
+    const overlayProps = {
+        isDismissable,
+        isKeyboardDismissDisabled,
+        isOpen,
+        defaultOpen,
+        onOpenChange,
+        isEntering,
+        isExiting,
+        shouldCloseOnInteractOutside,
+        UNSTABLE_deferUntilEntered,
+        UNSTABLE_overrideFocus,
+    };
+    return resolveOverlay(overlayProps, undefined, otherProps);
+}
+const OVERLAY_KEYS = [
+    "isDismissable",
+    "isKeyboardDismissDisabled",
+    "isOpen",
+    "defaultOpen",
+    "onOpenChange",
+    "isEntering",
+    "isExiting",
+    "shouldCloseOnInteractOutside",
+    "UNSTABLE_deferUntilEntered",
+    "UNSTABLE_overrideFocus",
+];
+/** Live props (P5): dismiss flags read at interaction time when live. */
+const LIVE_KEYS = ["isDismissable", "isKeyboardDismissDisabled", "isEntering", "isExiting"];
+/** A ModalOverlay is a wrapper for a Modal which allows customizing the backdrop element (RAC `ModalOverlay`). */
+export function ModalOverlay(props) {
+    const [merged, ref] = contextProps(props, props.ref, ModalContext);
+    return resolveOverlay(liveOptions(merged, LIVE_KEYS, ["isOpen"]), ref);
+}
+function resolveOverlay(props, ref, modal) {
+    const contextState = useContext(OverlayTriggerStateContext);
+    const localState = untrack(() => createOverlayTriggerState(props));
+    const state = untrack(() => props.isOpen != null || props.defaultOpen != null) || !contextState ? localState : contextState;
+    if (state === contextState && isDev() && (props.onOpenChange || props.defaultOpen !== undefined || props.isOpen !== undefined)) {
+        console.warn("This modals state is controlled by a trigger, place onOpenChange on the trigger instead.");
+    }
+    const portal = useContext(PortalContext);
+    const dialogContext = useContext(DialogContext);
+    // Own binding site: on a resumed page the first open re-creates only the overlay.
+    return (<span data-rv-overlay-anchor="" style={{ display: "contents" }}>
+      <ModalOverlayPresence props={props} ref={ref} state={state} portal={portal} dialogContext={dialogContext} modal={modal}/>
+    </span>);
+}
+function ModalOverlayPresence(resolved) {
+    const { props, state } = resolved;
+    const overlayRef = createRef();
+    const modalRef = createRef();
+    const onExit = props.onExit;
+    const modalExit = {};
+    // Object literal values, not arguments / local consts passed as arguments: the animation effects capture them (R2).
+    const fns = {
+        isOpen: () => state.isOpen(),
+        onOverlayExit: (element) => {
+            const user = onExit?.(element);
+            const exits = presences.get(modalExit)?.take();
+            return exits ? Promise.all([user, exits]).then(() => undefined) : user;
+        },
+        onModalExit: (element) => modalExit.current?.(element),
+    };
+    // Exits of nested `@rivetjs/motion` elements: a presence scope over the open state, only when Motion is in the bundle
+    // (it fills kit `overlayPresence`; nothing here otherwise). Kept in a module map keyed by `modalExit`, never
+    // captured: closures capture eagerly (resume) and the presence holds functions.
+    const presence = overlayPresence.create?.(fns.isOpen);
+    if (presence)
+        presences.set(modalExit, presence);
+    // Exit states here, their effects inside the branch (`watchExitAnimation` in ModalOverlayInner): a closed modal
+    // records no client effect, so a resumed page with a closed Modal / Drawer does not boot the runtime at load.
+    const overlayExit = createExitAnimationState(fns.isOpen);
+    const modalExitState = createExitAnimationState(fns.isOpen);
+    const isExitingProp = props.isExiting;
+    const isExiting = computed(() => overlayExit.isExiting() || modalExitState.isExiting() || !!read(isExitingProp) || false);
+    return (<Show when={() => state.isOpen() || isExiting()}>
+      {() => {
+            const inner = () => (<ModalOverlayInner {...resolved} overlayRef={overlayRef} modalRef={modalRef} isExiting={isExiting} modalExit={modalExit} exits={{ overlay: overlayExit, modal: modalExitState, onOverlayExit: fns.onOverlayExit, onModalExit: fns.onModalExit }}/>);
+            const presence = presences.get(modalExit);
+            return presence ? presence.wrap(inner) : inner();
+        }}
+    </Show>);
+}
+const OWNED = ["style", "onPointerDown"];
+function ModalOverlayInner(resolved) {
+    const { props, state, overlayRef, modalRef, isExiting, modalExit, dialogContext, exits } = resolved;
+    watchExitAnimation(overlayRef, exits.overlay, exits.onOverlayExit);
+    watchExitAnimation(modalRef, exits.modal, exits.onModalExit);
+    // Motion token (`--rv-motion-spring`, `modalHooks.open`): registered by @rivetjs/ui's overlays; cdk alone pays nothing.
+    // Read through the module object (by reference on resumed pages, never captured).
+    if (modalHooks.open)
+        clientEffect(() => {
+            const overlay = overlayRef(), modal = modalRef();
+            // A microtask later: after the portal mount puts the overlay in the document, where the token inherits.
+            if (overlay && modal)
+                queueMicrotask(() => modalHooks.open?.(overlay, modal));
+        });
+    const deferUntilEntered = !!props.UNSTABLE_deferUntilEntered;
+    // RA: revealed after `runAfterKeyboard` (an auto-focused input may open the on-screen keyboard).
+    // Rivet: a server-rendered overlay is already revealed (true is serialized), so a resumed page never runs the
+    // enter animation's not-ready hide: its effects may run before this one at load, which flashed the open overlay
+    // hidden and left an empty `style=""` on the overlay / modal elements (resume fuzz `/modal-open`, ui `/drawer-open`).
+    const isOpen = signal(typeof document === "undefined");
+    clientEffect(() => {
+        isOpen.set(true);
+    });
+    const onEnter = props.onEnter;
+    const enterFns = { onEnter: (element) => onEnter?.(element) };
+    const entered = createEnterAnimation(overlayRef, isOpen, enterFns.onEnter);
+    const isEnteringProp = props.isEntering;
+    const entering = () => entered() || !!read(isEnteringProp) || false;
+    const isDeferred = () => deferUntilEntered && (!isOpen() || entering());
+    const modalOptions = {
+        isDismissable: props.isDismissable,
+        isKeyboardDismissDisabled: props.isKeyboardDismissDisabled,
+        shouldCloseOnInteractOutside: props.shouldCloseOnInteractOutside,
+        overrideFocus: props.UNSTABLE_overrideFocus,
+    };
+    // The portal move is a client effect that may run after this one (a client render: content effects first): hiding
+    // the outside before the move hid the page's siblings of the in-place anchor instead of the page around the portal
+    // (RA: createPortal places the modal before useModalOverlay's layout effect). `onPlaced` gates it.
+    const placed = signal(false);
+    // useModalOverlay while open: released on close (the exit animation runs unblocked) and on unmount.
+    clientEffect(() => {
+        const element = modalRef();
+        if (!element || !state.isOpen() || !placed())
+            return;
+        const isEntering = isDeferred();
+        return untrack(() => modalOverlay(element, { ...modalOptions, isEntering }, state));
+    });
+    // Pass the entering state to the dialog so it waits to move focus until the modal has entered.
+    const mergedDialogContext = deferUntilEntered ? mergeDialogContext(dialogContext, { isEntering: isDeferred }) : dialogContext;
+    const values = { isEntering: entering, isExiting, state };
+    const rp = renderProps({ class: props.class, style: props.style, children: props.children, values, defaultClassName: "rv-ModalOverlay" }, hasLive(props) ? liveRenderProps(props) : undefined);
+    // useViewportSize + page size (browser only).
+    const viewport = signal(null);
+    // Capture the style accessor only: `rp` also holds `children` (a JSX slot, not serializable).
+    const userStyle = rp.style;
+    clientEffect(() => untrack(() => {
+        // RA useViewportSize: the shared viewport signal, mirrored into this overlay's signal.
+        const { size, dispose } = viewportSize();
+        viewport.set(size());
+        const win = window, target = win.visualViewport ?? win;
+        const sync = () => queueMicrotask(() => viewport.set(size()));
+        target.addEventListener("resize", sync);
+        return () => {
+            target.removeEventListener("resize", sync);
+            dispose();
+        };
+    }));
+    const style = () => {
+        const vp = viewport();
+        let pageWidth, pageHeight;
+        if (vp && typeof document !== "undefined") {
+            const scrollingElement = isScrollable(document.body) ? document.body : document.scrollingElement || document.documentElement;
+            // Prevent Firefox from adding scrollbars when the page has a fractional width/height.
+            const rect = scrollingElement.getBoundingClientRect();
+            pageWidth = scrollingElement.scrollWidth - (rect.width % 1);
+            pageHeight = scrollingElement.scrollHeight - (rect.height % 1);
+        }
+        return {
+            position: "fixed",
+            inset: "0",
+            zIndex: 100,
+            ...userStyle(),
+            "--visual-viewport-width": vp ? vp.width + "px" : undefined,
+            "--visual-viewport-height": vp ? vp.height + "px" : undefined,
+            "--page-width": pageWidth !== undefined ? pageWidth + "px" : undefined,
+            "--page-height": pageHeight !== undefined ? pageHeight + "px" : undefined,
+        };
+    };
+    const dom = globalDOMProps(props, OWNED);
+    const onPointerDown = props.onPointerDown;
+    const ref = mergeRefValues(overlayRef, resolved.ref);
+    const internal = { modalRef, isOpen, isExiting, isDismissable: props.isDismissable, onExit: modalExit, state };
+    const modal = resolved.modal;
+    const id = props.id, slot = props.slot ?? undefined;
+    const providerValues = () => [
+        [InternalModalContext, internal],
+        [OverlayTriggerStateContext, state],
+        [DialogContext, mergedDialogContext],
+        // RA Overlay's ClearPressResponder: the trigger's PressResponder must not reach buttons inside.
+        [PressResponderContext, { register: () => { } }],
+    ];
+    const overlayAttrs = props.render && {
+        ...dom,
+        id,
+        slot,
+        class: () => rp.class(),
+        style,
+        ref,
+        "data-entering": () => dataBool(entering()),
+        "data-exiting": () => dataBool(isExiting()),
+        onPointerDown: (event) => {
+            modalUnderlayPointerDown(event);
+            onPointerDown?.(event);
+        },
+        children: () => <Provider values={providerValues()}>{modal ? <ModalContent props={modal} ctx={internal}/> : rp.children()}</Provider>,
+    };
+    if (props.render)
+        return (<Overlay portalContainer={resolved.portal} shouldContainFocus isExiting={isExiting()} onPlaced={() => placed.set(true)}>
+        {props.render(overlayAttrs, values)}
+      </Overlay>);
+    return (<Overlay portalContainer={resolved.portal} shouldContainFocus isExiting={isExiting()} onPlaced={() => placed.set(true)}>
+      <div {...dom} id={id} slot={slot} class={rp.class()} style={style()} ref={ref} data-entering={dataBool(entering())} data-exiting={dataBool(isExiting())} onPointerDown={(event) => {
+            modalUnderlayPointerDown(event);
+            onPointerDown?.(event);
+        }}>
+        <Provider values={[
+            [InternalModalContext, internal],
+            [OverlayTriggerStateContext, state],
+            [DialogContext, mergedDialogContext],
+            // RA Overlay's ClearPressResponder: the trigger's PressResponder must not reach buttons inside.
+            [PressResponderContext, { register: () => { } }],
+        ]}>
+          {modal ? <ModalContent props={modal} ctx={internal}/> : rp.children()}
+        </Provider>
+      </div>
+    </Overlay>);
+}
+function mergeDialogContext(context, props) {
+    if (context && "slots" in context && context.slots) {
+        const slots = {};
+        for (const key in context.slots)
+            slots[key] = { ...context.slots[key], ...props };
+        return { ...context, slots };
+    }
+    return { ...context, ...props };
+}
+/** The modal element (RAC `ModalContent`): render props, `data-entering` / `data-exiting`, DismissButton. */
+function ModalContent(input) {
+    const { props, ctx } = input;
+    const { modalRef, isExiting, isDismissable, isOpen, state } = ctx;
+    const ref = mergeRefValues(modalRef, props.ref);
+    const onEnter = props.onEnter;
+    const enterFns = { onEnter: (element) => onEnter?.(element) };
+    const entering = createEnterAnimation(modalRef, isOpen, enterFns.onEnter);
+    // RA: `onExitRef.current = props.onExit` (layout effect) — the overlay's exit animation of this element calls it.
+    ctx.onExit.current = props.onExit;
+    const values = { isEntering: entering, isExiting, state };
+    const rp = renderProps({ class: props.class, style: props.style, children: props.children, values, defaultClassName: "rv-Modal" }, hasLive(props) ? liveRenderProps(props) : undefined);
+    const dom = globalDOMProps(props, ["style"]);
+    const id = props.id, slot = props.slot ?? undefined;
+    if (props.render) {
+        const attrs = {
+            ...dom,
+            id,
+            slot,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            ref,
+            "data-rv-overlay": "",
+            "data-entering": () => dataBool(entering()),
+            "data-exiting": () => dataBool(isExiting()),
+            children: () => [
+                typeof isDismissable === "function" ? (<Show when={isDismissable}>{() => <DismissButton onDismiss={() => closeOverlay(state)}/>}</Show>) : isDismissable ? (<DismissButton onDismiss={() => closeOverlay(state)}/>) : null,
+                <Provider values={[[InternalModalContext, null]]}>{rp.children()}</Provider>,
+            ],
+        };
+        return props.render(attrs, values);
+    }
+    return (<div {...dom} id={id} slot={slot} class={rp.class()} style={rp.style()} ref={ref} data-rv-overlay="" data-entering={dataBool(entering())} data-exiting={dataBool(isExiting())}>
+      {typeof isDismissable === "function" ? (
+        // Live props (P5): a live `isDismissable` shows / hides the DismissButton.
+        <Show when={isDismissable}>{() => <DismissButton onDismiss={() => closeOverlay(state)}/>}</Show>) : isDismissable ? (<DismissButton onDismiss={() => closeOverlay(state)}/>) : null}
+      {/* Deviation: cleared for the content, so a nested DialogTrigger's <Modal> opens its own overlay
+            (RAC leaves it set: a nested Modal would render inline as this overlay's modal). */}
+      <Provider values={[[InternalModalContext, null]]}>{rp.children()}</Provider>
+    </div>);
+}
+const isDev = () => globalThis.process?.env?.NODE_ENV === "development";
+/** @internal Opens / closes a modal state (re-exported for callers of the old API). */
+export { setOpen };
+// react-aria hooks (useModal / ModalProvider / OverlayContainer).
+export * from "./provider.jsx";

package/modal/provider.d.ts

@@ -0,0 +1,47 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import { type PortalMount } from "../portal/index.jsx";
+/**
+ * Children of the providers below: content (plain JSX children are a lazy compiler slot rendered
+ * under the provider, `renderSlot`) or a function returning it.
+ */
+export type ProviderChildren = Content | (() => Content);
+/** Id of the enclosing modal provider element (render time). */
+export declare const ModalProviderContext: import("@rivetjs/reactivity").Context<string | null>;
+/** Attributes of a modal provider element: `data-overlay-container`, its id, its parent provider. */
+export declare function modalProviderProps(id: string, parent?: string | null): Record<string, string | undefined>;
+/**
+ * Make `children` belong to the provider element with id `id` (render it with
+ * `modalProviderProps(id, parent)`); React Aria `ModalProvider` (+ `useModalProvider`).
+ */
+export declare function ModalProvider(props: {
+    id: string;
+    children?: ProviderChildren;
+}): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** A root that is `aria-hidden` while a modal of a nested provider is open (React Aria `OverlayProvider`). */
+export declare function OverlayProvider(props: {
+    id?: string;
+    class?: string;
+    children?: ProviderChildren;
+}): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/**
+ * Overlays like modals rendered in a portal at the end of body (or `portalContainer`), inside their
+ * own provider; the providers around it are hidden while a modal inside is open.
+ */
+export declare function OverlayContainer(props: {
+    portalContainer?: PortalMount;
+    class?: string;
+    children?: ProviderChildren;
+}): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface AriaModalOptions {
+    isDisabled?: boolean;
+}
+/** Attributes of the modal content element (`data-ismodal`, for the aria-modal polyfill). */
+export declare function modalProps(options?: AriaModalOptions): {
+    "data-ismodal": boolean;
+};
+/**
+ * The modal `element` opened (React Aria `useModal`): hide every provider above the one containing
+ * it (its logical parents). Returns the release function. Throws when `element` is not inside a
+ * provider, like React Aria.
+ */
+export declare function modal(element: Element, options?: AriaModalOptions): () => void;

package/modal/provider.jsx

@@ -0,0 +1,105 @@
+// Modal providers (React Aria `ModalProvider` / `OverlayProvider` / `OverlayContainer` / `useModal`):
+// while a modal is open, every provider *around* the one containing it is `aria-hidden`, so only
+// the top-most modal is reachable by screen readers. React counts modals through context; Rivet
+// links providers at render time instead (an `OverlayContainer` records its logical parent provider
+// in `data-rv-modal-parent`, which survives the portal move), and `modal()` — called when the modal
+// opens, in a handler — walks that chain, counting per provider (`data-rv-modal-count`).
+// For portaled modals (the overlay layer).
+//
+// Ported from @react-aria/overlays (useModal.tsx), Apache-2.0, © Adobe.
+import { createContext, useContext } from "@rivetjs/reactivity";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { Provider } from "@rivetjs/runtime/dom";
+import { createId } from "../utils/id.js";
+import { Portal, PortalContext } from "../portal/index.jsx";
+import { renderSlot } from "@rivetjs/runtime/slot";
+const content = (children) => renderSlot(children);
+/** Id of the enclosing modal provider element (render time). */
+export const ModalProviderContext = resumableContext(createContext(null, { id: "rv-modal" }));
+/** Attributes of a modal provider element: `data-overlay-container`, its id, its parent provider. */
+export function modalProviderProps(id, parent = null) {
+    return { "data-overlay-container": "", id, "data-rv-modal-parent": parent ?? undefined };
+}
+/**
+ * Make `children` belong to the provider element with id `id` (render it with
+ * `modalProviderProps(id, parent)`); React Aria `ModalProvider` (+ `useModalProvider`).
+ */
+export function ModalProvider(props) {
+    const children = props.children;
+    return (<Provider token={ModalProviderContext} value={props.id}>
+      {content(children)}
+    </Provider>);
+}
+/** A root that is `aria-hidden` while a modal of a nested provider is open (React Aria `OverlayProvider`). */
+export function OverlayProvider(props) {
+    const id = props.id ?? createId();
+    const parent = useContext(ModalProviderContext);
+    // Read before the JSX: an element with a spread resumes as one binding over all its attributes,
+    // and reading `props` there would capture the whole props object (children included).
+    const className = props.class;
+    return (<div {...modalProviderProps(id, parent)} class={className}>
+      <ModalProvider id={id}>{props.children}</ModalProvider>
+    </div>);
+}
+/**
+ * Overlays like modals rendered in a portal at the end of body (or `portalContainer`), inside their
+ * own provider; the providers around it are hidden while a modal inside is open.
+ */
+export function OverlayContainer(props) {
+    const container = props.portalContainer ?? useContext(PortalContext);
+    return (<Portal mount={container}>
+      <OverlayProvider class={props.class}>{props.children}</OverlayProvider>
+    </Portal>);
+}
+/** Attributes of the modal content element (`data-ismodal`, for the aria-modal polyfill). */
+export function modalProps(options) {
+    return { "data-ismodal": !options?.isDisabled };
+}
+const COUNT = "data-rv-modal-count";
+function adjust(provider, by) {
+    const count = Math.max(0, (Number(provider.getAttribute(COUNT)) || 0) + by);
+    if (count) {
+        provider.setAttribute(COUNT, String(count));
+        provider.setAttribute("aria-hidden", "true");
+    }
+    else {
+        provider.removeAttribute(COUNT);
+        provider.removeAttribute("aria-hidden");
+    }
+}
+/**
+ * The modal `element` opened (React Aria `useModal`): hide every provider above the one containing
+ * it (its logical parents). Returns the release function. Throws when `element` is not inside a
+ * provider, like React Aria.
+ */
+export function modal(element, options) {
+    const own = element.closest("[data-overlay-container]");
+    if (!own)
+        throw new Error("Modal is not contained within a provider");
+    if (options?.isDisabled)
+        return () => { };
+    const doc = element.ownerDocument;
+    const parents = [];
+    // The immediate provider stays visible; its parents are hidden.
+    for (let id = own.getAttribute("data-rv-modal-parent"); id;) {
+        const parent = doc.getElementById(id);
+        if (!parent || parents.includes(parent))
+            break;
+        parents.push(parent);
+        id = parent.getAttribute("data-rv-modal-parent");
+    }
+    // A provider outside any OverlayContainer: DOM ancestors are its parents.
+    if (!parents.length)
+        for (let p = own.parentElement?.closest("[data-overlay-container]"); p; p = p.parentElement?.closest("[data-overlay-container]"))
+            parents.push(p);
+    for (const parent of parents)
+        adjust(parent, 1);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        for (const parent of parents)
+            adjust(parent, -1);
+    };
+}

package/morph/index.d.ts

@@ -0,0 +1,91 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type ControlledState } from "../interactions/controllable.js";
+/** Logical direction the surface grows toward (`start` / `end` mirror in RTL). */
+export type MorphDirection = "top" | "top-end" | "end" | "bottom-end" | "bottom" | "bottom-start" | "start" | "top-start";
+export interface MorphStateProps {
+    /** Whether the surface is expanded (controlled): a plain value, a two-way Signal or an accessor. */
+    isOpen?: boolean | Signal<boolean> | (() => boolean);
+    /** Initial expanded state (uncontrolled). @default false */
+    defaultOpen?: boolean;
+    /** Called when the open state changes. */
+    onOpenChange?: (isOpen: boolean) => void;
+    /** Whether opening is disabled. */
+    isDisabled?: boolean;
+}
+export interface MorphState {
+    /** The open state (read `state.open.value()` in bindings). */
+    readonly open: ControlledState<boolean>;
+    readonly isDisabled: boolean;
+}
+/** Morph open state (react-stately `useControlledState` semantics through `controllable`). */
+export declare function createMorphState(props?: MorphStateProps): MorphState;
+/** Whether the morph is open (tracked read). */
+export declare const isMorphOpen: (state: MorphState) => boolean;
+export interface MorphMotionOptions {
+    /** Base duration (embla `duration`, fixed 60 Hz steps; lower = stiffer). @default 10 */
+    duration?: number;
+    /** Base friction (embla; lower = less damping). @default 0.6 */
+    friction?: number;
+}
+/** Default morph duration (embla units). */
+export declare const MORPH_DURATION = 10;
+/** Default morph friction. */
+export declare const MORPH_FRICTION = 0.6;
+/** Whether morphs on `root` jump (reduced motion or `data-animation="disabled"`). */
+export declare function morphReducesMotion(root: Element): boolean;
+/**
+ * Morphs `root` to its open (`true`) or collapsed state. Idempotent per target; a call mid-morph retargets the running
+ * motion (velocity kept). `onSettle` runs once the surface rests at the new target (also when jumping).
+ */
+export declare function morphTo(root: HTMLElement, open: boolean, options?: MorphMotionOptions & {
+    jump?: boolean;
+    onSettle?: () => void;
+}): void;
+/** Whether a morph is running on `root`. */
+export declare const isMorphing: (root: Element) => boolean;
+/** A viewport rect + corner radius (px). */
+export interface MorphRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    r: number;
+}
+export interface MorphRectOptions extends MorphMotionOptions {
+    /** The collapsed rect (p = 0), e.g. the source row's `getBoundingClientRect()`; read when a morph starts from rest. */
+    from: () => MorphRect;
+    /** The expanded rect (p = 1): where the surface rests open; read when a morph starts from rest. */
+    to: () => MorphRect;
+    /** Element whose inline `opacity` follows the progress (a dimming backdrop). */
+    backdrop?: HTMLElement | null;
+    /** Jump (no motion). Reduced motion / `data-animation="disabled"` on the surface jump too. */
+    jump?: boolean;
+    /** Runs once the surface rests at the new target. */
+    onSettle?: () => void;
+}
+/**
+ * Morphs a fixed-position `surface` between `from` (closed, p = 0) and `to` (open, p = 1): every frame writes the
+ * surface's inline `left` / `top` / `width` / `height` / `border-radius`, `--morph-progress` on it and the backdrop's
+ * `opacity` (no reads in the loop). Both rects are read once when a morph starts from rest; a call mid-morph retargets
+ * the running motion (velocity kept, no re-measure). The caller keeps the surface `position: fixed` and clips it
+ * (`overflow: hidden`).
+ */
+export declare function morphRectTo(surface: HTMLElement, open: boolean, options: MorphRectOptions): void;
+/** Current progress of a rect morph (0 closed … 1 open), or `undefined` when `surface` never morphed. */
+export declare const morphRectProgress: (surface: Element) => number | undefined;
+/** Finds the morph root an event / element belongs to. */
+export declare const morphRootOf: (el: EventTarget | null | undefined) => HTMLElement | null;
+/** Sets the open state and morphs `root` (when given) with focus + dismiss handling. */
+export declare function setMorphOpen(state: MorphState, open: boolean, root?: HTMLElement | null, motion?: MorphMotionOptions, restoreFocus?: boolean): void;
+/** Opens the morph (`root` = the morph root or any element inside it). */
+export declare const openMorph: (state: MorphState, el?: EventTarget | null, motion?: MorphMotionOptions) => void;
+/** Closes the morph. */
+export declare const closeMorph: (state: MorphState, el?: EventTarget | null, motion?: MorphMotionOptions) => void;
+/** Toggles the morph. */
+export declare const toggleMorph: (state: MorphState, el?: EventTarget | null, motion?: MorphMotionOptions) => void;
+/**
+ * Morphs `root` to `open` and wires focus + dismissal: opening installs Escape / outside-press / focus-out listeners
+ * (they call `setMorphOpen(state, false, root)`), moves focus into the panel; closing removes them and returns focus to the
+ * trigger. Safe to call repeatedly (controlled state followers call it from an effect).
+ */
+export declare function syncMorph(state: MorphState, root: HTMLElement, open: boolean, motion?: MorphMotionOptions, restoreFocus?: boolean): void;