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

package/utils/live-element.jsx

@@ -0,0 +1,76 @@
+// Live props (P5, docs/design/specs/2026-10-07-live-props-design.md §8): the live path of the plain text parts (Label,
+// Text, Header, Heading). Their static path destructures `class` / `style` / `children` into compiled templates;
+// with a live prop (own getter) this path renders one `Dynamic` element whose `class` / `style` / children read the
+// props inside bindings, and forwards every other prop through the spread unread.
+import { untrack } from "@rivetjs/reactivity";
+import { Dynamic } from "@rivetjs/runtime/dom";
+import { renderSlot } from "@rivetjs/runtime/slot";
+import { liveOmit } from "./live.jsx";
+import { liveRenderProps } from "../slots/index.jsx";
+const OWN = ["elementType", "children", "class", "style", "slot", "render", "ref"];
+/** `class` of live props (a returned arrow: resumable). */
+function liveClass(props, defaultClassName) {
+    // A function `class` (an accessor, e.g. ui's render-class) is called, as the static path's attribute binding does.
+    return () => {
+        const className = props.class;
+        return (typeof className === "function" ? className() : className) ?? defaultClassName;
+    };
+}
+/** `style` of live props: a value, or an accessor (a returned arrow: resumable). */
+function liveStyle(props) {
+    return () => {
+        const style = props.style;
+        return (typeof style === "function" ? style() : style);
+    };
+}
+/**
+ * The element of a live-props text part: `elementType` (read once), `class` / `style` / children live, the other
+ * props forwarded through the spread (`omit`: extra own keys of the part). `style` is a key only when it was set at
+ * creation (the server `Dynamic` rejects a `style` attribute name).
+ */
+export function liveElement(props, ref, elementType, defaultClassName, omit = []) {
+    const dom = liveOmit(props, [...OWN, ...omit]);
+    // Closures capture one narrow view per key, never the whole props object (a children function capturing a class
+    // instance must not reach the class / style bindings on a resumed page).
+    const [classView, styleView, childrenView] = liveRenderProps(props);
+    const hasStyle = untrack(() => props.style) !== undefined;
+    const slot = untrack(() => props.slot) ?? undefined;
+    const attrs = hasStyle
+        ? { class: liveClass(classView, defaultClassName), style: liveStyle(styleView) }
+        : { class: liveClass(classView, defaultClassName) };
+    const r = ref;
+    // Compiled templates for the parts' usual elements (a `Dynamic` element costs more on both targets).
+    switch (elementType) {
+        case "span":
+            return (<span {...dom} {...attrs} slot={slot} ref={r}>
+          {() => renderSlot(childrenView.children)}
+        </span>);
+        case "label":
+            return (<label {...dom} {...attrs} slot={slot} ref={r}>
+          {() => renderSlot(childrenView.children)}
+        </label>);
+        case "div":
+            return (<div {...dom} {...attrs} slot={slot} ref={r}>
+          {() => renderSlot(childrenView.children)}
+        </div>);
+        case "p":
+            return (<p {...dom} {...attrs} slot={slot} ref={r}>
+          {() => renderSlot(childrenView.children)}
+        </p>);
+        case "header":
+            return (<header {...dom} {...attrs} slot={slot} ref={r}>
+          {() => renderSlot(childrenView.children)}
+        </header>);
+        case "h2":
+            return (<h2 {...dom} {...attrs} slot={slot} ref={r}>
+          {() => renderSlot(childrenView.children)}
+        </h2>);
+        case "h3":
+            return (<h3 {...dom} {...attrs} slot={slot} ref={r}>
+          {() => renderSlot(childrenView.children)}
+        </h3>);
+    }
+    return (<Dynamic component={elementType} {...dom} {...attrs} slot={slot} ref={r}>
+      {() => renderSlot(childrenView.children)}
+    </Dynamic>);
+}

package/utils/live.d.ts

@@ -0,0 +1,53 @@
+/** Whether `object[key]` is an own getter (a live prop; a proxied spread source reports getters too). */
+export declare function isLive(object: object | null | undefined, key: PropertyKey): boolean;
+/** Whether any own enumerable key of `object` is a getter (live props present). */
+export declare function hasLive(object: object | null | undefined): boolean;
+/**
+ * A narrow view of `props` for the `keys` a part reads in bindings / handlers: a plain object of the present values
+ * when none of them is live (static path: a small data copy, serializes like locals), else a `splitProps` part that
+ * forwards every key to `props` unread (live path; on a resumed page it encodes as forwards, not values). Read
+ * `view.key` inside the binding.
+ */
+export declare function liveView<T extends object, const K extends readonly (keyof T)[]>(props: T, keys: K): Pick<T, K[number]>;
+/**
+ * A `MaybeAccessor` slot from a prop (cdk state factories / behaviour options read `read(v)` at use time): an
+ * accessor `() => read(view[key])` when `view[key]` is live, else the value itself (static path unchanged). Pass a
+ * `liveView` (narrow), not the whole props object: the accessor captures it.
+ */
+export declare function liveAt<T extends object, K extends keyof T>(view: T, key: K): T[K] | (() => Unwrap<T[K]>);
+/**
+ * A string `class` attribute of a live `class` prop (parts that take a plain `class`, not a render-prop one): an
+ * accessor over a narrow view (a function `class` is called), default `defaultClassName`. Goes into the element's
+ * spread bag (a function attribute value outside a spread is not a server binding).
+ */
+export declare function liveClass(props: object, defaultClassName: string): () => string;
+type Unwrap<V> = V extends () => infer R ? R : V;
+/**
+ * The accessor boundary of a part (cdk accessor rule: state-like props are `T | (() => T)`, read with `read(v)` in
+ * bindings / at event time): every live key of `keys` becomes an accessor data value (`liveAt`), so the part's
+ * copies (`{ ...props }`, destructures, state factories, behaviour bags) carry the accessor instead of a snapshot.
+ * `controlled` keys (a controlled value: `isSelected`, `value`, `isOpen`, …) become accessors only when defined at
+ * creation — an `undefined` one stays uncontrolled (React: switching between controlled and uncontrolled is
+ * unsupported); a controlled key holding a two-way Signal passes the Signal itself (stays two-way). Other keys forward unread. No live key → `props` itself (static path, 0 cost).
+ */
+export declare function liveOptions<T extends object>(props: T, keys: readonly (keyof T)[], controlled?: readonly (keyof T)[]): T;
+/**
+ * A controlled collection-selection prop (`selectedKeys` / `expandedKeys`: `"all"` or an iterable of keys) for a
+ * selection state: when live and defined at creation, an accessor that reads it and normalises it to a `Set` (or
+ * `"all"`) — the state treats a plain function as a controlled, never-written value; a forwarded two-way Signal, an
+ * `undefined` (uncontrolled) or a static value is returned as is (static path unchanged).
+ */
+export declare function liveKeys<T extends object, K extends keyof T>(props: T, key: K): T[K];
+/**
+ * `props` without `keys` (a rest destructure `const { a, ...rest } = props`, which reads every getter): a `splitProps`
+ * rest part when a prop is live (forwarding unread), else a plain copy (static path).
+ */
+export declare function liveOmit<T extends object, const K extends readonly (keyof T)[]>(props: T, keys: K): Omit<T, K[number]>;
+/** `removeDataAttributes` (RAC) for live props: the `data-*` keys split off unread when a prop is live. */
+export declare function liveWithoutData<T extends object>(props: T): T;
+/** The current values of `keys`, read untracked (read-once props in a part body: no region dependency on a resumed page). */
+export declare function readOnce<T extends object, const K extends readonly (keyof T)[]>(props: T, keys: K): Pick<T, K[number]>;
+/** `{ ...base, ...extra }` without reading `base`'s getters when a prop is live (runtime `mergeProps`: a defined `extra`
+ *  value wins), else the plain spread (static path). */
+export declare function liveAssign<T extends object, U extends object>(base: T, extra: U): T & U;
+export {};

package/utils/live.jsx

@@ -0,0 +1,169 @@
+// Rivet-only (no React Aria counterpart): live component props in the cdk (live props P5,
+// docs/design/specs/2026-10-07-live-props-design.md §8). The compiler passes a prop whose value reads state as an own
+// getter (`<Button aria-pressed={on()}>` → `{ get "aria-pressed"() { return on(); } }`); a static prop is a data
+// property. A cdk part runs once, so it must not copy a getter's value at creation: these helpers keep getters
+// unread (runtime `splitProps` forwards) and read them where React re-renders — inside bindings and at event time.
+// Static props (no getter, every server render) take the copy path: same objects, same cost as before.
+// A `.tsx` module (resume-compiled): the accessor `liveAt` returns is a resumable symbol over its narrow view.
+import { untrack } from "@rivetjs/reactivity";
+import { mergeProps as mergeLive, splitProps } from "@rivetjs/runtime/props";
+/** Whether `object[key]` is an own getter (a live prop; a proxied spread source reports getters too). */
+export function isLive(object, key) {
+    return !!object && Object.getOwnPropertyDescriptor(object, key)?.get !== undefined;
+}
+/** Whether any own enumerable key of `object` is a getter (live props present). */
+export function hasLive(object) {
+    if (!object)
+        return false;
+    const keys = Object.keys(object);
+    for (let i = 0; i < keys.length; i++)
+        if (Object.getOwnPropertyDescriptor(object, keys[i])?.get !== undefined)
+            return true;
+    return false;
+}
+/**
+ * A narrow view of `props` for the `keys` a part reads in bindings / handlers: a plain object of the present values
+ * when none of them is live (static path: a small data copy, serializes like locals), else a `splitProps` part that
+ * forwards every key to `props` unread (live path; on a resumed page it encodes as forwards, not values). Read
+ * `view.key` inside the binding.
+ */
+export function liveView(props, keys) {
+    const out = {};
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const desc = Object.getOwnPropertyDescriptor(props, key);
+        if (desc === undefined)
+            continue;
+        if (desc.get !== undefined)
+            return splitProps(props, keys)[0];
+        out[key] = desc.value;
+    }
+    return out;
+}
+/**
+ * A `MaybeAccessor` slot from a prop (cdk state factories / behaviour options read `read(v)` at use time): an
+ * accessor `() => read(view[key])` when `view[key]` is live, else the value itself (static path unchanged). Pass a
+ * `liveView` (narrow), not the whole props object: the accessor captures it.
+ */
+export function liveAt(view, key) {
+    if (Object.getOwnPropertyDescriptor(view, key)?.get === undefined)
+        return view[key];
+    return () => {
+        const value = view[key];
+        return (typeof value === "function" ? value() : value);
+    };
+}
+/**
+ * A string `class` attribute of a live `class` prop (parts that take a plain `class`, not a render-prop one): an
+ * accessor over a narrow view (a function `class` is called), default `defaultClassName`. Goes into the element's
+ * spread bag (a function attribute value outside a spread is not a server binding).
+ */
+export function liveClass(props, defaultClassName) {
+    const view = liveView(props, ["class"]);
+    return () => {
+        const value = view.class;
+        return (typeof value === "function" ? value() : value) ?? defaultClassName;
+    };
+}
+const isSignal = (v) => typeof v === "function" && typeof v.set === "function";
+/**
+ * The accessor boundary of a part (cdk accessor rule: state-like props are `T | (() => T)`, read with `read(v)` in
+ * bindings / at event time): every live key of `keys` becomes an accessor data value (`liveAt`), so the part's
+ * copies (`{ ...props }`, destructures, state factories, behaviour bags) carry the accessor instead of a snapshot.
+ * `controlled` keys (a controlled value: `isSelected`, `value`, `isOpen`, …) become accessors only when defined at
+ * creation — an `undefined` one stays uncontrolled (React: switching between controlled and uncontrolled is
+ * unsupported); a controlled key holding a two-way Signal passes the Signal itself (stays two-way). Other keys forward unread. No live key → `props` itself (static path, 0 cost).
+ */
+export function liveOptions(props, keys, controlled = []) {
+    let over;
+    let view;
+    // `keys` then `controlled` by index: the joined list is built only for the live view (static path: no array).
+    const n = keys.length, total = n + controlled.length;
+    for (let i = 0; i < total; i++) {
+        const key = i < n ? keys[i] : controlled[i - n];
+        if (!isLive(props, key))
+            continue;
+        if (i >= n) {
+            const now = untrack(() => props[key]);
+            if (now === undefined)
+                continue;
+            // A forwarded two-way Signal (`isSelected={sig}` through a wrapper's getter) stays two-way: pass the Signal itself.
+            if (isSignal(now)) {
+                (over ??= {})[key] = now;
+                continue;
+            }
+        }
+        view ??= splitProps(props, (controlled.length ? [...keys, ...controlled] : keys))[0];
+        (over ??= {})[key] = liveAt(view, key);
+    }
+    return over ? mergeLive(props, over) : props;
+}
+/**
+ * A controlled collection-selection prop (`selectedKeys` / `expandedKeys`: `"all"` or an iterable of keys) for a
+ * selection state: when live and defined at creation, an accessor that reads it and normalises it to a `Set` (or
+ * `"all"`) — the state treats a plain function as a controlled, never-written value; a forwarded two-way Signal, an
+ * `undefined` (uncontrolled) or a static value is returned as is (static path unchanged).
+ */
+export function liveKeys(props, key) {
+    if (!isLive(props, key))
+        return props[key];
+    const now = untrack(() => props[key]);
+    if (now == null || isSignal(now))
+        return now;
+    const view = splitProps(props, [key])[0];
+    return (() => {
+        const value = view[key];
+        return value === "all" || value instanceof Set ? value : new Set(value);
+    });
+}
+/**
+ * `props` without `keys` (a rest destructure `const { a, ...rest } = props`, which reads every getter): a `splitProps`
+ * rest part when a prop is live (forwarding unread), else a plain copy (static path).
+ */
+export function liveOmit(props, keys) {
+    if (hasLive(props))
+        return splitProps(props, keys)[1];
+    const out = {};
+    for (const key in props)
+        if (!keys.includes(key))
+            out[key] = props[key];
+    return out;
+}
+/** `removeDataAttributes` (RAC) for live props: the `data-*` keys split off unread when a prop is live. */
+export function liveWithoutData(props) {
+    if (hasLive(props)) {
+        const data = [];
+        for (const key in props)
+            if (key.startsWith("data-"))
+                data.push(key);
+        return splitProps(props, data)[1];
+    }
+    // Static path: stop at the first `data-*` key (no key list).
+    let found = false;
+    for (const key in props)
+        if (key.startsWith("data-")) {
+            found = true;
+            break;
+        }
+    if (!found)
+        return { ...props };
+    const out = {};
+    for (const key in props)
+        if (!key.startsWith("data-"))
+            out[key] = props[key];
+    return out;
+}
+/** The current values of `keys`, read untracked (read-once props in a part body: no region dependency on a resumed page). */
+export function readOnce(props, keys) {
+    return untrack(() => {
+        const out = {};
+        for (const key of keys)
+            out[key] = props[key];
+        return out;
+    });
+}
+/** `{ ...base, ...extra }` without reading `base`'s getters when a prop is live (runtime `mergeProps`: a defined `extra`
+ *  value wins), else the plain spread (static path). */
+export function liveAssign(base, extra) {
+    return (hasLive(base) ? mergeLive(base, extra) : { ...base, ...extra });
+}

package/utils/load-more-sentinel.d.ts

@@ -0,0 +1,28 @@
+import type { Collection } from "../collections/types.js";
+type MaybeAccessor<T> = T | (() => T);
+export interface LoadMoreSentinelProps {
+    /** The collection the sentinel trails; the observer is re-created whenever it changes. */
+    collection: MaybeAccessor<Collection<any> | null | undefined>;
+    /** Handler that is called when more items should be loaded, e.g. while scrolling near the bottom. */
+    onLoadMore?: () => any;
+    /**
+     * The amount of offset from the bottom of your scrollable region that should trigger load more.
+     * Uses a percentage value relative to the scroll body's client height. Load more is then
+     * triggered when your current scroll position's distance from the bottom of the currently loaded
+     * list of items is less than or equal to the provided value. (e.g. 1 = 100% of the scroll
+     * region's height).
+     *
+     * @default 1
+     */
+    scrollOffset?: MaybeAccessor<number | undefined>;
+    /**
+     * The scroll direction that triggers load more. Use 'start' for reversed layouts where older
+     * content loads when scrolling toward the top.
+     *
+     * @default 'end'
+     */
+    direction?: MaybeAccessor<"start" | "end" | undefined>;
+}
+/** Calls `props.onLoadMore` whenever the sentinel element `ref` scrolls within `scrollOffset` of its scroll parent's viewport. */
+export declare function loadMoreSentinel(props: LoadMoreSentinelProps, ref: () => HTMLElement | null | undefined): void;
+export {};

package/utils/load-more-sentinel.jsx

@@ -0,0 +1,52 @@
+// Ported from packages/react-aria/src/utils/useLoadMoreSentinel.ts, Apache-2.0, © Adobe.
+// Rivet:
+// - Name: `useLoadMoreSentinel` → `loadMoreSentinel(props, ref)` (no `use*` exports).
+// - `.tsx` (no JSX): `.ts` modules are not server-rewritten, and this one calls `clientEffect`.
+// - `useLayoutEffect(…, [collection, ref, scrollOffset, direction])` → `clientEffect` that tracks the
+//   same inputs: `ref` is an element accessor (`ref()` from `@rivetjs/runtime/dom`), `collection`,
+//   `scrollOffset` and `direction` a value or an accessor. Any change tears the observer down and sets up
+//   a new one, as upstream.
+// - `useEffectEvent(triggerLoadMore)` → `props.onLoadMore` read when the observer fires (always the latest).
+import { untrack } from "@rivetjs/reactivity";
+import { clientEffect } from "@rivetjs/runtime/dom";
+import { getScrollParent } from "./dom.js";
+const read = (value) => (typeof value === "function" ? value() : value);
+/** Calls `props.onLoadMore` whenever the sentinel element `ref` scrolls within `scrollOffset` of its scroll parent's viewport. */
+export function loadMoreSentinel(props, ref) {
+    const triggerLoadMore = (entries) => {
+        // Use "isIntersecting" over an equality check of 0 since it seems like there is cases where
+        // a intersection ratio of 0 can be reported when isIntersecting is actually true
+        for (const entry of entries) {
+            // Note that this will be called if the collection changes, even if onLoadMore was already called and is being processed.
+            // Up to user discretion as to how to handle these multiple onLoadMore calls
+            const onLoadMore = props.onLoadMore;
+            if (entry.isIntersecting && onLoadMore)
+                untrack(() => onLoadMore());
+        }
+    };
+    clientEffect(() => {
+        // Dependencies: collection, ref, scrollOffset, direction.
+        read(props.collection);
+        const element = ref();
+        const scrollOffset = read(props.scrollOffset) ?? 1;
+        const direction = read(props.direction) ?? "end";
+        let sentinelObserver = null;
+        if (element) {
+            // Tear down and set up a new IntersectionObserver when the collection changes so that we can properly trigger additional loadMores if there is room for more items
+            // Need to do this tear down and set up since using a large rootMargin will mean the observer's callback isn't called even when scrolling the item into view beause its visibility hasn't actually changed
+            // https://codesandbox.io/p/sandbox/magical-swanson-dhgp89?file=%2Fsrc%2FApp.js%3A21%2C21
+            const margin = 100 * scrollOffset;
+            // For direction='start', right/left margins have no affect for vertical scroll containers. We are not supporting reverse horizontal scroll containers for now.
+            const rootMargin = direction === "start" ? `${margin}% 0px 0px 0px` : `0px ${margin}% ${margin}% ${margin}%`;
+            sentinelObserver = new IntersectionObserver(triggerLoadMore, {
+                root: getScrollParent(element),
+                rootMargin,
+            });
+            sentinelObserver.observe(element);
+        }
+        return () => {
+            if (sentinelObserver)
+                sentinelObserver.disconnect();
+        };
+    });
+}

package/utils/motion-token.d.ts

@@ -0,0 +1,4 @@
+/** Spring (visualDuration, bounce: Motion's parameters, mass 1) → `linear()` points + settling time. */
+export declare function springCurve(visualDuration: number, bounce: number): readonly [easing: string, duration: string];
+/** Apply the motion token read from `element` (call once per open, element in the document). */
+export declare function applyMotionToken(element: HTMLElement): void;

package/utils/motion-token.js

@@ -0,0 +1,48 @@
+// Motion token (motion spec D17): `--rv-motion-spring: <visualDuration s> <bounce>` (e.g. `0.3 0.2`) on an overlay or an
+// ancestor switches its enter / exit animations to a spring: CSS `linear()` easing + the spring's settling time, set
+// inline (beats the theme's classes). Read once per open; unset (the default) or reduced motion = no change. No JS
+// animation engine: the overlay's own CSS keyframes / transitions run on the spring curve.
+const curves = new Map();
+/** Spring (visualDuration, bounce: Motion's parameters, mass 1) → `linear()` points + settling time. */
+export function springCurve(visualDuration, bounce) {
+    const k = ((2 * Math.PI) / (visualDuration * 1.2)) ** 2;
+    const w = Math.sqrt(k);
+    const zeta = 1 - Math.min(Math.max(bounce, 0), 1);
+    const x = zeta < 1
+        ? (t) => {
+            const wd = w * Math.sqrt(1 - zeta * zeta);
+            return 1 - Math.exp(-zeta * w * t) * (Math.cos(wd * t) + ((zeta * w) / wd) * Math.sin(wd * t));
+        }
+        : (t) => 1 - Math.exp(-w * t) * (1 + w * t);
+    // Settled: within 0.1 % of the target for the rest of the curve (capped at 2 s).
+    let end = 2;
+    for (let t = 2; t > 0; t -= 0.01)
+        if (Math.abs(1 - x(t)) > 0.001)
+            break;
+        else
+            end = t;
+    const points = [];
+    for (let i = 0; i <= 40; i++)
+        points.push(String(Math.round(x((end * i) / 40) * 1000) / 1000));
+    points[40] = "1";
+    return [`linear(${points.join(",")})`, Math.round(end * 1000) + "ms"];
+}
+/** Apply the motion token read from `element` (call once per open, element in the document). */
+export function applyMotionToken(element) {
+    const token = getComputedStyle(element).getPropertyValue("--rv-motion-spring").trim();
+    if (!token || matchMedia("(prefers-reduced-motion: reduce)").matches)
+        return;
+    let curve = curves.get(token);
+    if (curve === undefined) {
+        const [duration, bounce] = token.split(/\s+/).map(Number);
+        curve = duration > 0 ? springCurve(duration, bounce || 0) : null;
+        curves.set(token, curve);
+    }
+    if (!curve)
+        return;
+    const style = element.style;
+    style.setProperty("animation-timing-function", curve[0]);
+    style.setProperty("animation-duration", curve[1]);
+    style.setProperty("transition-timing-function", curve[0]);
+    style.setProperty("transition-duration", curve[1]);
+}

package/utils/render.d.ts

@@ -0,0 +1,19 @@
+import type { JSX } from "@rivetjs/runtime/jsx-runtime";
+export type DOMRenderFunction<E extends keyof JSX.IntrinsicElements, T> = (props: JSX.IntrinsicElements[E], renderProps: T) => JSX.Element;
+export interface DOMRenderProps<E extends keyof JSX.IntrinsicElements, T> {
+    /** Overrides the default DOM element with a custom render function; spread the received props onto the element you render. */
+    render?: DOMRenderFunction<E, T>;
+}
+/**
+ * The part's attributes go to `render` when given, else to the default element (`fallback`).
+ * Rivet parts do NOT use this with a JSX `fallback` arrow: a compiled element in a callback loses the part's
+ * resumable bindings (reactive `children`, adopted server nodes). Parts write `if (render) return render(attrs, rp);`
+ * before their compiled element instead; this stays for non-JSX fallbacks and as the documented contract.
+ */
+export declare function renderElement<E extends keyof JSX.IntrinsicElements, T>(render: DOMRenderFunction<E, T> | undefined, props: JSX.IntrinsicElements[E], renderProps: T, fallback: (props: JSX.IntrinsicElements[E]) => JSX.Element): JSX.Element;
+/**
+ * Client/SSR fresh-render only (a new arrow in a `.ts` module is not resumable): used only on the `render` path, which never
+ * adopts server nodes. `children` for a part's attributes object: lazy JSX content is resolved once; a user function is reactive
+ * content, so it stays an accessor (the element's spread re-renders the content when its reads change).
+ */
+export declare function slotChildren<T>(children: T | (() => T)): unknown;

package/utils/render.js

@@ -0,0 +1,18 @@
+import { isSlot, renderSlot } from "@rivetjs/runtime/slot";
+/**
+ * The part's attributes go to `render` when given, else to the default element (`fallback`).
+ * Rivet parts do NOT use this with a JSX `fallback` arrow: a compiled element in a callback loses the part's
+ * resumable bindings (reactive `children`, adopted server nodes). Parts write `if (render) return render(attrs, rp);`
+ * before their compiled element instead; this stays for non-JSX fallbacks and as the documented contract.
+ */
+export function renderElement(render, props, renderProps, fallback) {
+    return render ? render(props, renderProps) : fallback(props);
+}
+/**
+ * Client/SSR fresh-render only (a new arrow in a `.ts` module is not resumable): used only on the `render` path, which never
+ * adopts server nodes. `children` for a part's attributes object: lazy JSX content is resolved once; a user function is reactive
+ * content, so it stays an accessor (the element's spread re-renders the content when its reads change).
+ */
+export function slotChildren(children) {
+    return typeof children === "function" && !isSlot(children) ? () => renderSlot(children) : renderSlot(children);
+}

package/utils/transitions.d.ts

@@ -0,0 +1,15 @@
+/** Focus `element` without scrolling it into view (`focus({ preventScroll: true })`, Baseline). */
+export declare function focusWithoutScrolling(element: HTMLElement | SVGElement): void;
+/**
+ * Start tracking transitions in `doc` (react-aria does this at import; Rivet modules have no
+ * import-time effects, so the first `runAfterTransition` call does it). Transitions already running
+ * then are picked up from `document.getAnimations()`.
+ */
+export declare function trackTransitions(doc?: Document): void;
+/** Test hook: stop tracking and forget running transitions and queued callbacks. */
+export declare function _resetTransitions(): void;
+/**
+ * Run `fn` once every running CSS transition in the document finished (`fn(true)`), or on the next
+ * frame when none runs (`fn(false)`; one frame lets a transition on mount start). Returns a cancel function.
+ */
+export declare function runAfterTransition(fn: (isTransition: boolean) => void): () => void;

package/utils/transitions.js

@@ -0,0 +1,104 @@
+// react-aria `focusWithoutScrolling` + `runAfterTransition` (Apache-2.0, © Adobe; ported in `./index.ts` before
+// DOCS-COLD 2026-10-20). A leaf module: no imports, so the focus / overlay helpers that need these two do not reach
+// `./index.ts` (which re-exports `merge-props`); `./index.ts` re-exports them.
+/** Focus `element` without scrolling it into view (`focus({ preventScroll: true })`, Baseline). */
+export function focusWithoutScrolling(element) {
+    element.focus({ preventScroll: true });
+}
+// --- runAfterTransition ---------------------------------------------------------------------------
+// Elements currently transitioning → their transitioning CSS properties (a set, not a count: Chrome
+// sometimes fires both transitionend and transitioncancel).
+const transitionsByElement = new Map();
+const transitionCallbacks = new Set();
+let tracking = null;
+const isTransitionEvent = (event) => "propertyName" in event;
+const eventTarget = (event) => {
+    try {
+        return event.composedPath?.()[0] ?? event.target;
+    }
+    catch {
+        return event.target;
+    }
+};
+function onTransitionStart(event) {
+    const target = eventTarget(event);
+    if (!isTransitionEvent(event) || !target)
+        return;
+    let transitions = transitionsByElement.get(target);
+    if (!transitions) {
+        transitionsByElement.set(target, (transitions = new Set()));
+        // On the element itself: it must fire even when the node is removed mid-transition.
+        target.addEventListener("transitioncancel", onTransitionEnd, { once: true });
+    }
+    transitions.add(event.propertyName);
+}
+function onTransitionEnd(event) {
+    const target = eventTarget(event);
+    if (!isTransitionEvent(event) || !target)
+        return;
+    const properties = transitionsByElement.get(target);
+    if (!properties)
+        return;
+    properties.delete(event.propertyName);
+    if (properties.size === 0) {
+        target.removeEventListener("transitioncancel", onTransitionEnd);
+        transitionsByElement.delete(target);
+    }
+    if (transitionsByElement.size === 0) {
+        for (const callback of transitionCallbacks) {
+            callback(true);
+            transitionCallbacks.delete(callback);
+        }
+    }
+}
+/**
+ * Start tracking transitions in `doc` (react-aria does this at import; Rivet modules have no
+ * import-time effects, so the first `runAfterTransition` call does it). Transitions already running
+ * then are picked up from `document.getAnimations()`.
+ */
+export function trackTransitions(doc = document) {
+    if (tracking === doc)
+        return;
+    tracking = doc;
+    doc.addEventListener("transitionrun", onTransitionStart);
+    doc.addEventListener("transitionend", onTransitionEnd);
+    try {
+        for (const animation of doc.getAnimations?.() ?? []) {
+            const css = animation;
+            const target = css.effect?.target;
+            if (css.transitionProperty && target && animation.playState === "running")
+                onTransitionStart(Object.assign(new Event("transitionrun"), { propertyName: css.transitionProperty, composedPath: () => [target] }));
+        }
+    }
+    catch { }
+}
+/** Test hook: stop tracking and forget running transitions and queued callbacks. */
+export function _resetTransitions() {
+    tracking?.removeEventListener("transitionrun", onTransitionStart);
+    tracking?.removeEventListener("transitionend", onTransitionEnd);
+    tracking = null;
+    transitionsByElement.clear();
+    transitionCallbacks.clear();
+}
+function cleanupDetachedElements() {
+    for (const [target] of transitionsByElement)
+        if ("isConnected" in target && !target.isConnected)
+            transitionsByElement.delete(target);
+}
+/**
+ * Run `fn` once every running CSS transition in the document finished (`fn(true)`), or on the next
+ * frame when none runs (`fn(false)`; one frame lets a transition on mount start). Returns a cancel function.
+ */
+export function runAfterTransition(fn) {
+    trackTransitions();
+    const frame = requestAnimationFrame(() => {
+        cleanupDetachedElements();
+        if (transitionsByElement.size === 0)
+            return fn(false);
+        transitionCallbacks.add(fn);
+    });
+    return () => {
+        cancelAnimationFrame(frame);
+        transitionCallbacks.delete(fn);
+    };
+}