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

package/utils/animation.jsx

@@ -0,0 +1,236 @@
+// Ported from packages/react-aria/src/utils/animation.ts (useEnterAnimation, useExitAnimation), Apache-2.0, © Adobe.
+// Rivet:
+// - Names: `useEnterAnimation` → `createEnterAnimation`, `useExitAnimation` → `createExitAnimation` (no `use*` exports).
+// - `.tsx` (no JSX): `.ts` modules are not server-rewritten, and this one calls `clientEffect`.
+// - React state → signals; both hooks return an accessor (`isEntering()` / `isExiting()`) that bindings
+//   read (`data-entering={dataBool(isEntering())}`); `ref` is a `ref()` (or any element accessor),
+//   `isReady` / `isOpen` a value or an accessor.
+// - `useLayoutEffect` → `clientEffect` (runs in the microtask after the element mounted, before paint).
+// - `useEffectEvent(onStart)` → the callback is read untracked when the animation starts; pass a wrapper
+//   (`(el) => props.onEnter?.(el)`) to always call the latest one.
+// - `flushSync(onEnd)` → a plain signal write (bindings update synchronously).
+// - `useExitAnimation`'s render-phase `setExitState` → a computed holding the state machine.
+// Deviation: an overlay rendered open by the server (or re-created by a resumed page from a branch the server
+// rendered shown, `_serverBranch() >= 0`) is not entering — React Aria never server-renders overlays, Rivet
+// does, and its HTML is the settled open state. Created in the browser (incl. the first open of a branch the
+// server rendered closed: key -1 / null) → entering.
+// Deviation: with no running animation and the element not yet carrying its `data-entering` / `data-exiting`
+// attribute (a resumed page commits that binding after the effect), the end waits a microtask for the CSS
+// animation the attribute starts; with the attribute present it ends at once (RA).
+import { _regionState, computed, signal, untrack } from "@rivetjs/reactivity";
+import { _serverBranch, clientEffect } from "@rivetjs/runtime/dom";
+import { chain } from "../interactions/merge-props.jsx";
+import { setStyle } from "./dom.js";
+const read = (value) => (typeof value === "function" ? value() : value);
+/** Whether this element is being created in the browser (not server-rendered, not adopted from the server). */
+// Entering unless the server rendered this branch shown: `_serverBranch()` is the adopted Show key while a
+// resumed page re-creates a region (match index ≥ 0 = server rendered it shown; -1 fallback / null never
+// adopted = the server rendered it closed, so the first open after resume enters), `undefined` otherwise.
+const createdInBrowser = () => {
+    if (typeof document === "undefined")
+        return false;
+    const key = _serverBranch();
+    return key === undefined || key === null || key < 0;
+};
+/**
+ * Entry animation state of `ref` (react-aria `useEnterAnimation`): true from creation until the element's
+ * running CSS animations / transitions and the promise `onEnter` returns have finished. While `isReady`
+ * is false the element is hidden with non-layout styles and the animation waits (popovers before placement).
+ */
+export function createEnterAnimation(ref, isReady = true, onEnter) {
+    const isEntering = signal(createdInBrowser());
+    const isAnimationReady = () => isEntering() && read(isReady);
+    // Hide the element while it prepares for entry, using only non-layout-thrashing attributes.
+    // This prevents accidental flashes of content in scenarios where no hidden styling is applied
+    // while the enter animation is not yet ready (e.g. popovers prior to placement calculation).
+    clientEffect(() => {
+        const element = ref();
+        if (!read(isReady) && element) {
+            return chain(setStyle(element, "opacity", "0"), setStyle(element, "clip", "rect(0 0 0 0)"), setStyle(element, "clip-path", "inset(50%)"), setStyle(element, "mask-image", "linear-gradient(#0000, #0000)"));
+        }
+    });
+    // There are two cases for entry animations:
+    // 1. CSS @keyframes. The `animation` property is set during the isEntering state, and it is removed after the animation finishes.
+    // 2. CSS transitions. The initial styles are applied during the isEntering state, and removed immediately, causing the transition to occur.
+    //
+    // In the second case, cancel any transitions that were triggered prior to the isEntering = false state (when the transition is supposed to start).
+    // This can happen when isReady starts as false (e.g. popovers prior to placement calculation).
+    clientEffect(() => {
+        const element = ref();
+        if (isAnimationReady() && element && "getAnimations" in element) {
+            for (const animation of element.getAnimations()) {
+                if (typeof CSSTransition !== "undefined" && animation instanceof CSSTransition)
+                    animation.cancel();
+            }
+        }
+    });
+    // Object literal value, not an inline argument: the effect captures it, so it must be resumable (R2).
+    const done = { end: () => isEntering.set(false) };
+    useAnimation(ref, isAnimationReady, onEnter, done.end, "data-entering");
+    return isAnimationReady;
+}
+/**
+ * Exit animation state of `ref` (react-aria `useExitAnimation`): true from the moment `isOpen` turns false
+ * until the element's running animations and the promise `onExit` returns have finished — keep the element
+ * mounted while it is true. Reopening interrupts the exit.
+ */
+export function createExitAnimation(ref, isOpen, onExit) {
+    const exit = createExitAnimationState(isOpen);
+    watchExitAnimation(ref, exit, onExit);
+    return exit.isExiting;
+}
+/**
+ * Rivet: {@link createExitAnimation} without its client effect — create the state where the open / exiting
+ * condition is read, call {@link watchExitAnimation} where the element exists (inside the branch that stays
+ * mounted while exiting). A closed overlay then records no client effect, so a resumed page with closed
+ * tooltips does not boot the runtime at load.
+ */
+export function createExitAnimationState(isOpen) {
+    // Deviation: whether it was open at creation is region state: a resumed page re-creating the region on the close
+    // (dismissing a server-open overlay first) gets the server's `true` back and exits, instead of unmounting at once.
+    let exitState = _regionState(() => untrack(() => read(isOpen))) ? "open" : "closed";
+    // Each finished exit bumps `ended`; the state machine below closes on it.
+    const ended = signal(0);
+    let seen = 0;
+    const isExiting = computed(() => {
+        const open = read(isOpen);
+        const end = ended();
+        if (end !== seen) {
+            seen = end;
+            // Set the state to closed, which will cause the element to be unmounted.
+            if (exitState === "exiting")
+                exitState = "closed";
+        }
+        switch (exitState) {
+            case "open":
+                // If isOpen becomes false, set the state to exiting.
+                if (!open)
+                    exitState = "exiting";
+                break;
+            case "closed":
+            case "exiting":
+                // If we are exiting and isOpen becomes true, the animation was interrupted.
+                // Reset the state to open.
+                if (open)
+                    exitState = "open";
+                break;
+        }
+        return exitState === "exiting";
+    });
+    return { isExiting, end: () => ended.update((n) => n + 1) };
+}
+/** The effect half of {@link createExitAnimation}: waits for the exit animations of `ref`, then `exit.end()`. */
+export function watchExitAnimation(ref, exit, onExit) {
+    useAnimation(ref, exit.isExiting, onExit, exit.end, "data-exiting");
+}
+function useAnimation(ref, isActive, onStart, onEnd, 
+/** The state attribute the element's binding writes (`data-entering` / `data-exiting`). */
+attribute) {
+    let wasActive = null;
+    clientEffect(() => {
+        const active = isActive();
+        const element = ref();
+        if (active && element && wasActive !== active) {
+            wasActive = active;
+            const start = () => {
+                if (!("getAnimations" in element)) {
+                    // JSDOM
+                    onEnd();
+                    return;
+                }
+                const startPromise = onStart?.(element);
+                const animations = running(element);
+                if (animations.length === 0 && !startPromise && element.hasAttribute(attribute)) {
+                    onEnd();
+                    return;
+                }
+                if (animations.length === 0 && !startPromise) {
+                    // Deviation: on a resumed page the element's state binding (`data-entering` / `data-exiting`) can
+                    // commit after this effect, so the CSS animation it starts is not running yet: look again after
+                    // the pending bindings (a microtask; RA's layout effect always runs after the commit) before ending.
+                    queueMicrotask(() => {
+                        const wait = () => {
+                            const later = element.isConnected ? running(element) : [];
+                            if (later.length === 0)
+                                onEnd();
+                            // Cancelled (moved into the portal host): wait for the restarted ones.
+                            else
+                                Promise.all(later.map((a) => a.finished)).then(onEnd, wait);
+                        };
+                        wait();
+                    });
+                    return;
+                }
+                // Deviation: RA swallows a rejected `finished` (cancelled animation) and never ends. A Rivet overlay is
+                // moved into its portal host right after mount, which restarts its CSS animation (the first one is
+                // cancelled): then wait for the animations running at that point, while the element is in the document.
+                // (`finished` is read at once: a cancelled animation's next `finished` is a new pending promise.)
+                // Deviation: a rejected start promise (a user `onEnter` / `onExit`) ends the animation and reports the error
+                // (RA ends nothing: with held exit fills below, the overlay would stay mounted, invisible, its underlay and
+                // focus containment active).
+                let ended = false;
+                const end = () => {
+                    if (!ended) {
+                        ended = true;
+                        onEnd();
+                    }
+                };
+                Promise.resolve(startPromise).catch((error) => {
+                    end();
+                    (globalThis.reportError ?? console.error)(error);
+                });
+                // Deviation (Rivet `onEnter` / `onExit` promise, e.g. a nested `@rivetjs/motion` exit in cdk Modal): when the
+                // promise outlives the element's own CSS animations, they hold their end state instead of snapping the element
+                // back to its open styles until the unmount (a backdrop flashed opaque while a longer Motion exit ran).
+                const hold = (list) => {
+                    if (startPromise)
+                        for (const a of list)
+                            if ("animationName" in a)
+                                a.effect?.updateTiming({ fill: "forwards" });
+                };
+                hold(animations);
+                const settle = (finished) => {
+                    Promise.all(finished).then(end, () => {
+                        if (!ended && element.isConnected) {
+                            const later = running(element);
+                            hold(later);
+                            settle([startPromise, ...later.map((a) => a.finished)]);
+                        }
+                    });
+                };
+                if (!startPromise)
+                    settle(animations.map((a) => a.finished));
+                else
+                    // A CSS animation the state binding starts after this effect (a resumed page re-creating the region on its
+                    // first interaction, e.g. dismissing a server-open modal) is held and awaited too: collect a microtask later.
+                    queueMicrotask(() => {
+                        const all = element.isConnected ? running(element) : [];
+                        for (const a of animations)
+                            if (!all.includes(a))
+                                all.push(a);
+                        hold(all);
+                        settle([startPromise, ...all.map((a) => a.finished)]);
+                    });
+            };
+            // Deviation: an overlay's portal host is moved into its mount by the Portal's own client effect, queued after
+            // this one (the overlay's state is created before its `<Overlay>`). Moving re-inserts the element: a CSS
+            // transition keyed on `data-entering` (drawer / sheet backdrops) needs its entering style computed in the final
+            // position, else ending here leaves no before-change style and the element snaps to its open state. So the enter
+            // starts a microtask later, after the mount's queued effects (RA's layout effect runs after the commit, with the
+            // portal content already in place). Exit animations start in place (nothing moves; nested `@rivetjs/motion`
+            // exits are collected by the overlay's presence scope after the close's bindings ran, cdk Modal).
+            if (attribute === "data-entering")
+                queueMicrotask(() => untrack(start));
+            else
+                untrack(start);
+            return;
+        }
+        wasActive = active;
+    });
+}
+/** The element's running document-timeline animations (RA's filter). */
+function running(element) {
+    return element
+        .getAnimations()
+        .filter((a) => (typeof DocumentTimeline === "undefined" || a.timeline instanceof DocumentTimeline) && a.playState === "running");
+}

package/utils/data-attrs.d.ts

@@ -0,0 +1,71 @@
+import type { Signal } from "@rivetjs/reactivity";
+import { type HoverEvents } from "../interactions/hover.jsx";
+import { type MaybeAccessor } from "../interactions/utils.js";
+/** A boolean render-state attribute value: `"true"` or absent (RAC `data-x="true"`; never `""`). */
+export declare const dataBool: (value: unknown) => "true" | undefined;
+/** Set (`"true"`) or remove the boolean state attribute `name` on `el`. */
+export declare function setDataAttr(el: Element, name: string, value: boolean): void;
+/** Optional signals mirroring the attributes (for function render props). */
+export interface InteractionStateSignals {
+    isHovered?: Signal<boolean>;
+    isFocused?: Signal<boolean>;
+    isFocusVisible?: Signal<boolean>;
+}
+export interface InteractionStateOptions extends HoverEvents {
+    /** Disables hover (RA `useHover({ isDisabled })`; not the focus events); read at event time. */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+    /** Focus ring when a descendant has focus (RA `useFocusRing({ within })`): writes `data-focus-within` (not
+     * `data-focused`); `states.isFocused` = focus within. Bind `onFocusIn` / `onFocusOut` (both delegated). */
+    within?: boolean;
+    /** Text input: only Tab / Escape make focus visible. */
+    isTextInput?: boolean;
+    /** User focus events (RA `useFocus`), called from the same handlers. */
+    onFocus?: (e: FocusEvent) => void;
+    onBlur?: (e: FocusEvent) => void;
+    onFocusChange?: (isFocused: boolean) => void;
+    /** Signals the handlers keep in sync with the attributes. */
+    states?: InteractionStateSignals;
+}
+/** pointerover (delegated; bind `onPointerOver`): an enter sets `data-hovered` (+ `onHoverStart` / `onHoverChange`);
+ * the hovered element's `pointerleave` (bound while hovered) removes it (+ `onHoverEnd` / `onHoverChange`). */
+export declare function hoverStateOver(o: InteractionStateOptions, e: PointerEvent): void;
+/** pointerenter (a native listener per element; prefer `hoverStateOver`): `data-hovered` (+ `onHoverStart` / `onHoverChange`). */
+export declare function hoverStateEnter(o: InteractionStateOptions, e: PointerEvent): void;
+/** pointerleave of `hoverStateEnter` callers: ends the hover now (the transient leave listener then finds none). */
+export declare function hoverStateLeave(o: InteractionStateOptions, e: PointerEvent): void;
+/** End a hover now (RA: `isDisabled` turning true while hovered). */
+export declare function endHoverState(el: Element): void;
+/**
+ * focusin (delegated; bind `onFocusIn`, not with `within`): the element's own focus (React's onFocus is focusin,
+ * RA useFocus checks `target === currentTarget`) → `focusStateFocus`, and its native `blur` binds until it fires
+ * (→ `focusStateBlur`). No listener per element.
+ */
+export declare function focusStateIn(o: InteractionStateOptions, e: FocusEvent): void;
+/** focus (or focusin with `within`): `data-focused` (`data-focus-within`), `data-focus-visible` (+ user focus events). */
+export declare function focusStateFocus(o: InteractionStateOptions, e: FocusEvent): void;
+/** blur (bound by `focusStateIn`), or focusout with `within`: removes `data-focused`, `data-focus-visible` (+ user focus events). */
+export declare function focusStateBlur(o: InteractionStateOptions, e: FocusEvent): void;
+/**
+ * Handler bag for an element without its own handlers for these events: spread it
+ * (`<div {...interactionStateProps(o)}>`) or `mergeProps` it. Builds the handlers as object literal
+ * values (R2: resumable); all delegated (no listener per element). Components wiring explicit `onX` call the
+ * `*State*` functions instead.
+ */
+export declare function interactionStateProps(o: InteractionStateOptions): Record<string, unknown>;
+/**
+ * RA `useFocusable`'s `FocusableContext` merge for components that render their own focusable element (Button,
+ * Link): `ctx` = `useContext(FocusableContext)` (TooltipTrigger / PreviewTrigger trigger props). Returns
+ * `[props, ref, attrs]`:
+ * - event handlers (`on[A-Z]…`) chain after the component's own (RA `mergeProps(focusableProps, contextProps)`);
+ * - other context props fill only what the component's props leave `undefined` (its own props win);
+ * - `attrs`: the context's DOM attributes (`aria-*`, `data-*`, `id`, `role`, `title`, …) the props leave
+ *   `undefined`, for the element: spread `{...readAttrs(attrs)}` (accessor values allowed);
+ * - a disabled element takes none (RA: `isDisabled ? {} : domProps`); the context `ref` is returned for
+ *   `mergeRefValues`.
+ */
+export declare function mergeFocusableContext<P extends object>(props: P, ctx: {
+    ref?: unknown;
+    [key: string]: unknown;
+} | null | undefined, isDisabled?: boolean): [P, unknown, Record<string, unknown> | undefined];
+/** `attrs` with accessor values read (call inside the element's spread binding: `{...readAttrs(attrs)}`). */
+export declare function readAttrs(attrs: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/utils/data-attrs.jsx

@@ -0,0 +1,193 @@
+import { endHover, hoverPointerLeave, hoverPointerOver } from "../interactions/hover.jsx";
+import { focusRingBlur, focusRingFocus } from "../focus/focus-ring.jsx";
+import { focusBlur, focusFocus } from "../interactions/focus.jsx";
+import { getEventTarget } from "../interactions/utils.js";
+import { chain2 } from "../interactions/merge-props.jsx";
+import { mergeProps as mergeLive } from "@rivetjs/runtime/props";
+import { hasLive } from "./live.jsx";
+/** A boolean render-state attribute value: `"true"` or absent (RAC `data-x="true"`; never `""`). */
+export const dataBool = (value) => (value ? "true" : undefined);
+/** Set (`"true"`) or remove the boolean state attribute `name` on `el`. */
+export function setDataAttr(el, name, value) {
+    if (value)
+        el.setAttribute(name, "true");
+    else
+        el.removeAttribute(name);
+}
+const states = new WeakMap();
+const stateOf = (el) => {
+    let s = states.get(el);
+    if (!s)
+        states.set(el, (s = {}));
+    return s;
+};
+function hoverOf(el, o) {
+    const s = stateOf(el);
+    const hover = (s.hover ??= {
+        props: o,
+        state: { isHovered: false, pointerType: "", target: null, globals: [] },
+        hovered: { set: (v) => (setDataAttr(el, "data-hovered", v), o.states?.isHovered?.set(v)) },
+    });
+    hover.props = o; // options are rebuilt per event: keep the latest callbacks
+    return hover;
+}
+function ringOf(el, o) {
+    const s = stateOf(el);
+    let focused = false;
+    // RAC: `data-focus-within` for a focus-within ring (Group), `data-focused` otherwise.
+    const focusAttr = o.within ? "data-focus-within" : "data-focused";
+    const ring = (s.ring ??= {
+        props: { within: o.within, isTextInput: o.isTextInput },
+        focused: Object.assign(() => focused, {
+            set: (v) => ((focused = v), setDataAttr(el, focusAttr, v), o.states?.isFocused?.set(v)),
+        }),
+        visible: { set: (v) => (setDataAttr(el, "data-focus-visible", v), o.states?.isFocusVisible?.set(v)) },
+        state: { isFocused: false, isFocusVisible: false, unsubscribe: null },
+    });
+    return ring;
+}
+/** pointerover (delegated; bind `onPointerOver`): an enter sets `data-hovered` (+ `onHoverStart` / `onHoverChange`);
+ * the hovered element's `pointerleave` (bound while hovered) removes it (+ `onHoverEnd` / `onHoverChange`). */
+export function hoverStateOver(o, e) {
+    hoverPointerOver(hoverOf(e.currentTarget, o), e);
+}
+/** pointerenter (a native listener per element; prefer `hoverStateOver`): `data-hovered` (+ `onHoverStart` / `onHoverChange`). */
+export function hoverStateEnter(o, e) {
+    if (e.target === e.currentTarget)
+        hoverStateOver(o, e);
+}
+/** pointerleave of `hoverStateEnter` callers: ends the hover now (the transient leave listener then finds none). */
+export function hoverStateLeave(o, e) {
+    hoverPointerLeave(hoverOf(e.currentTarget, o), e);
+}
+/** End a hover now (RA: `isDisabled` turning true while hovered). */
+export function endHoverState(el) {
+    const hover = states.get(el)?.hover;
+    if (hover)
+        endHover(hover);
+}
+/**
+ * focusin (delegated; bind `onFocusIn`, not with `within`): the element's own focus (React's onFocus is focusin,
+ * RA useFocus checks `target === currentTarget`) → `focusStateFocus`, and its native `blur` binds until it fires
+ * (→ `focusStateBlur`). No listener per element.
+ */
+export function focusStateIn(o, e) {
+    const el = e.currentTarget;
+    if (getEventTarget(e) !== el)
+        return;
+    bindBlur(el, o);
+    focusStateFocus(o, e);
+}
+/** focus (or focusin with `within`): `data-focused` (`data-focus-within`), `data-focus-visible` (+ user focus events). */
+export function focusStateFocus(o, e) {
+    // `isDisabled` is the hover switch (RAC: pending buttons stop hovering but keep their focus events).
+    if (!o.within && (o.onFocus || o.onFocusChange))
+        focusFocus({ onFocus: o.onFocus, onBlur: o.onBlur, onFocusChange: o.onFocusChange }, e);
+    focusRingFocus(ringOf(e.currentTarget, o), e);
+}
+/** The element's native `blur` while it is focused (one listener at a time per focused element). */
+function bindBlur(el, o) {
+    const s = stateOf(el);
+    s.unblur?.();
+    const onBlur = (event) => {
+        s.unblur?.();
+        focusStateBlur(o, event);
+    };
+    el.addEventListener("blur", onBlur);
+    s.unblur = () => (el.removeEventListener("blur", onBlur), (s.unblur = undefined));
+}
+/** blur (bound by `focusStateIn`), or focusout with `within`: removes `data-focused`, `data-focus-visible` (+ user focus events). */
+export function focusStateBlur(o, e) {
+    if (!o.within && (o.onBlur || o.onFocusChange))
+        focusBlur({ onFocus: o.onFocus, onBlur: o.onBlur, onFocusChange: o.onFocusChange }, e);
+    focusRingBlur(ringOf(e.currentTarget, o), e);
+}
+/**
+ * Handler bag for an element without its own handlers for these events: spread it
+ * (`<div {...interactionStateProps(o)}>`) or `mergeProps` it. Builds the handlers as object literal
+ * values (R2: resumable); all delegated (no listener per element). Components wiring explicit `onX` call the
+ * `*State*` functions instead.
+ */
+export function interactionStateProps(o) {
+    const focus = o.within
+        ? { onFocusIn: (e) => focusStateFocus(o, e), onFocusOut: (e) => focusStateBlur(o, e) }
+        : { onFocusIn: (e) => focusStateIn(o, e) };
+    return {
+        onPointerOver: (e) => hoverStateOver(o, e),
+        ...focus,
+    };
+}
+/** Context DOM attributes forwarded to the element (RA useFocusable merges every FocusableContext DOM prop). */
+const FORWARDED_ATTR = /^(?:aria-|data-)|^(?:id|role|title|lang|dir)$/;
+/**
+ * RA `useFocusable`'s `FocusableContext` merge for components that render their own focusable element (Button,
+ * Link): `ctx` = `useContext(FocusableContext)` (TooltipTrigger / PreviewTrigger trigger props). Returns
+ * `[props, ref, attrs]`:
+ * - event handlers (`on[A-Z]…`) chain after the component's own (RA `mergeProps(focusableProps, contextProps)`);
+ * - other context props fill only what the component's props leave `undefined` (its own props win);
+ * - `attrs`: the context's DOM attributes (`aria-*`, `data-*`, `id`, `role`, `title`, …) the props leave
+ *   `undefined`, for the element: spread `{...readAttrs(attrs)}` (accessor values allowed);
+ * - a disabled element takes none (RA: `isDisabled ? {} : domProps`); the context `ref` is returned for
+ *   `mergeRefValues`.
+ */
+export function mergeFocusableContext(props, ctx, isDisabled) {
+    if (!ctx)
+        return [props, undefined, undefined];
+    const { ref, ...domProps } = ctx;
+    if (isDisabled)
+        return [props, ref, undefined];
+    if (hasLive(props))
+        return liveFocusableMerge(props, ref, domProps);
+    const out = { ...props };
+    let attrs;
+    for (const key in domProps) {
+        const value = domProps[key];
+        const own = out[key];
+        if (/^on[A-Z]/.test(key) && typeof value === "function")
+            out[key] = typeof own === "function" ? chain2(own, value) : value;
+        else if (own === undefined) {
+            out[key] = value;
+            if (FORWARDED_ATTR.test(key))
+                (attrs ??= {})[key] = value;
+        }
+    }
+    return [out, ref, attrs];
+}
+// Live props (P5): own getters stay unread — runtime `mergeProps(context, props, handlers)`: own defined values win
+// per read (context fills `undefined`), context handlers chain after the own ones at call time.
+function liveFocusableMerge(props, ref, domProps) {
+    const own = props;
+    const handlers = {};
+    let attrs;
+    for (const key in domProps) {
+        const value = domProps[key];
+        if (/^on[A-Z]/.test(key) && typeof value === "function") {
+            if (Object.hasOwn(own, key))
+                handlers[key] = ownThen(own, key, value);
+        }
+        else if (FORWARDED_ATTR.test(key) && own[key] === undefined)
+            (attrs ??= {})[key] = value;
+    }
+    return [mergeLive(domProps, props, handlers), ref, attrs];
+}
+/** The own handler (read at call time), then the context's (a returned arrow: a resumable symbol). */
+function ownThen(own, key, then) {
+    return (...args) => {
+        const f = own[key];
+        if (typeof f === "function")
+            f(...args);
+        return then(...args);
+    };
+}
+/** `attrs` with accessor values read (call inside the element's spread binding: `{...readAttrs(attrs)}`). */
+export function readAttrs(attrs) {
+    if (!attrs)
+        return undefined;
+    const out = {};
+    for (const key in attrs) {
+        const v = attrs[key];
+        const value = typeof v === "function" ? v() : v;
+        out[key] = value == null ? undefined : String(value);
+    }
+    return out;
+}

package/utils/dev-off.d.ts

@@ -0,0 +1,3 @@
+export declare const DEV: boolean;
+/** Development-only (`dev-on.ts`); "" here. */
+export declare function devWhere(): string;

package/utils/dev-off.js

@@ -0,0 +1,7 @@
+// Production build (default resolution of the cdk `#dev` import, package.json): dev-only code folds away
+// (`if (DEV && …)`), so neither the warnings nor `devWhere` ship.
+export const DEV = false;
+/** Development-only (`dev-on.ts`); "" here. */
+export function devWhere() {
+    return "";
+}

package/utils/dev-on.d.ts

@@ -0,0 +1,3 @@
+export declare const DEV: boolean;
+/** `\n  in <…>` / `\n  at …` for the current dev caller, or "". */
+export declare function devWhere(): string;

package/utils/dev-on.js

@@ -0,0 +1,17 @@
+// Development build (`development` condition of the cdk `#dev` import, package.json): dev-only warnings run.
+// Rivet (not upstream): `devWhere()` says where a cdk development warning was triggered.
+// `globalThis[Symbol.for("rivet.locate")]` is installed by the dev runtime in the browser (`@rivetjs/runtime` dev/where.ts:
+// the component chain, `in <TextField> (src/form.tsx:4:17) ← <Page> (…)`) and by the compiler's Vite plugin on the dev
+// server (the app's source-mapped stack frames, `at Page (src/routes/index.tsx:12:7)`); plain Node has none → "".
+export const DEV = true;
+/** `\n  in <…>` / `\n  at …` for the current dev caller, or "". */
+export function devWhere() {
+    const locate = globalThis[Symbol.for("rivet.locate")];
+    try {
+        const text = typeof locate === "function" ? locate() : "";
+        return text ? "\n  " + text : "";
+    }
+    catch {
+        return "";
+    }
+}

package/utils/dom-props.d.ts

@@ -0,0 +1,44 @@
+import type { EventMap } from "@rivetjs/runtime/jsx-runtime";
+type GlobalEventName = "Click" | "AuxClick" | "ContextMenu" | "DblClick" | "MouseDown" | "MouseEnter" | "MouseLeave" | "MouseMove" | "MouseOut" | "MouseOver" | "MouseUp" | "TouchCancel" | "TouchEnd" | "TouchMove" | "TouchStart" | "PointerDown" | "PointerMove" | "PointerUp" | "PointerCancel" | "PointerEnter" | "PointerLeave" | "PointerOver" | "PointerOut" | "GotPointerCapture" | "LostPointerCapture" | "Scroll" | "Wheel" | "AnimationStart" | "AnimationEnd" | "AnimationIteration" | "TransitionCancel" | "TransitionEnd" | "TransitionRun" | "TransitionStart";
+/** Global DOM event props (`onPointerEnter`, `onWheelCapture`, …), typed with the native event. */
+export type GlobalDOMEvents<E extends Element = Element> = {
+    [K in GlobalEventName as `on${K}` | `on${K}Capture`]?: (event: EventMap[K] & {
+        currentTarget: E;
+    }) => void;
+};
+/** `data-*` attributes (RAC `filterDOMProps` forwards every one). */
+export type DataAttributes = {
+    [K in `data-${string}`]?: string | number | boolean | undefined;
+};
+/**
+ * Global DOM attributes forwarded to the root element (+ every `data-*` attribute). `style` is forwarded
+ * too but typed by the component (RAC `StyleProps` / `StyleRenderProps`), as upstream.
+ */
+export interface GlobalDOMAttributes<E extends Element = Element> extends GlobalDOMEvents<E>, DataAttributes {
+    dir?: "ltr" | "rtl" | "auto";
+    lang?: string;
+    hidden?: boolean;
+    inert?: boolean;
+    translate?: "yes" | "no";
+}
+/**
+ * The global DOM events and attributes set on `props`, minus the `owned` names the component
+ * handles itself. Spread the result on the root element: `<div {...globalDOMProps(props)} …>`.
+ */
+export declare function globalDOMProps(props: object, owned?: readonly string[]): Record<string, unknown>;
+type TextInputEventName = "Input" | "BeforeInput" | "CompositionStart" | "CompositionUpdate" | "CompositionEnd" | "Copy" | "Cut" | "Paste" | "Select";
+/**
+ * Text input DOM events (RA `TextInputDOMProps`, RAC `Input`): forwarded to the `<input>` /
+ * `<textarea>` of TextField, TextArea, ComboBox… (+ Capture).
+ */
+export type TextInputDOMEvents<E extends Element = HTMLInputElement> = {
+    [K in TextInputEventName as `on${K}` | `on${K}Capture`]?: (event: EventMap[K] & {
+        currentTarget: E;
+    }) => void;
+};
+/**
+ * The text input DOM events set on `props`, minus `owned` (default `onInput`: inputs handle it
+ * themselves and call the user's from their own). Spread the result on the input element.
+ */
+export declare function textInputDOMProps(props: object, owned?: readonly string[]): Record<string, unknown>;
+export {};

package/utils/dom-props.js

@@ -0,0 +1,73 @@
+import { splitProps } from "@rivetjs/runtime/props";
+const GLOBAL = /^(?:on(?:Click|AuxClick|ContextMenu|DblClick|Mouse(?:Down|Enter|Leave|Move|Out|Over|Up)|Touch(?:Cancel|End|Move|Start)|Pointer(?:Down|Move|Up|Cancel|Enter|Leave|Over|Out)|GotPointerCapture|LostPointerCapture|Scroll|Wheel|Animation(?:Start|End|Iteration)|Transition(?:Cancel|End|Run|Start))(?:Capture)?|dir|lang|hidden|inert|translate|style|data-[^\s]+)$/;
+/**
+ * The global DOM events and attributes set on `props`, minus the `owned` names the component
+ * handles itself. Spread the result on the root element: `<div {...globalDOMProps(props)} …>`.
+ */
+export function globalDOMProps(props, owned) {
+    return pick(props, GLOBAL, GLOBAL_KEYS, owned);
+}
+// Parse once per key string (docs/guides/performance.md): the alternation regex per prop key of every part root was
+// ~40% of `pick`; key → match, bounded so arbitrary user keys cannot grow it.
+const GLOBAL_KEYS = new Map(), TEXT_INPUT_KEYS = new Map();
+function matches(cache, pattern, key) {
+    let hit = cache.get(key);
+    if (hit === undefined) {
+        hit = pattern.test(key);
+        if (cache.size < 512)
+            cache.set(key, hit);
+    }
+    return hit;
+}
+// Live props (P5): a live key (own getter) is forwarded unread — the result is a `splitProps` part over the matching
+// keys, read by the element spread's binding; without getters the matching defined values are copied (as before).
+function pick(props, pattern, cache, owned) {
+    const out = {};
+    let keys;
+    for (const key in props) {
+        if (!matches(cache, pattern, key) || owned?.includes(key))
+            continue;
+        (keys ??= []).push(key);
+        const desc = Object.getOwnPropertyDescriptor(props, key);
+        if (desc?.get !== undefined)
+            return forward(props, keys.concat(rest(props, key, pattern, cache, owned)));
+        const value = desc ? desc.value : props[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+const PROXY = Symbol.for("rivet.props");
+/**
+ * A writable bag forwarding `keys` to `props` (components add attributes to it). A proxied props object (a spread of
+ * a call / conditional: runtime Proxy, whose parts discard writes) gets plain forwarding getters over the keys it
+ * has now.
+ */
+function forward(props, keys) {
+    if (props[PROXY] !== 1)
+        return splitProps(props, keys)[0];
+    const out = {};
+    for (const key of keys)
+        Object.defineProperty(out, key, { enumerable: true, configurable: true, get: () => props[key] });
+    return out;
+}
+/** The matching keys of `props` after `from` (live path: the whole key list for `splitProps`). */
+function rest(props, from, pattern, cache, owned) {
+    const keys = [];
+    let after = false;
+    for (const key in props) {
+        if (key === from)
+            after = true;
+        else if (after && matches(cache, pattern, key) && !owned?.includes(key))
+            keys.push(key);
+    }
+    return keys;
+}
+const TEXT_INPUT = /^on(?:Input|BeforeInput|Composition(?:Start|Update|End)|Copy|Cut|Paste|Select)(?:Capture)?$/;
+/**
+ * The text input DOM events set on `props`, minus `owned` (default `onInput`: inputs handle it
+ * themselves and call the user's from their own). Spread the result on the input element.
+ */
+export function textInputDOMProps(props, owned = ["onInput"]) {
+    return pick(props, TEXT_INPUT, TEXT_INPUT_KEYS, owned);
+}