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

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/types.d.ts

@@ -0,0 +1,111 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import type { RivetKeyboardEvent } from "../interactions/keyboard.jsx";
+import type { ValidationResult } from "../state/form-validation.js";
+export type { PressEvent, PressEvents, PointerType } from "../interactions/press.jsx";
+export type { HoverEvent, HoverEvents } from "../interactions/hover.jsx";
+export type { RivetKeyboardEvent as KeyboardEvent } from "../interactions/keyboard.jsx";
+export type { Key, Selection, SelectionMode, SelectionBehavior, FocusStrategy, DisabledBehavior, Orientation, Direction, LoadingState, SortDescriptor, SortDirection, } from "../collections/types.js";
+export type { Href, RouterOptions, LinkDOMProps } from "./links.jsx";
+export type { ValidationResult, ValidationErrors, ValidationFunction, ValidationBehavior } from "../state/form-validation.js";
+export type { GlobalDOMAttributes, GlobalDOMEvents } from "./dom-props.js";
+export interface KeyboardEvents {
+    /** Handler that is called when a key is pressed. */
+    onKeyDown?: (e: RivetKeyboardEvent) => void;
+    /** Handler that is called when a key is released. */
+    onKeyUp?: (e: RivetKeyboardEvent) => void;
+}
+export interface FocusEvents<Target extends Element = Element> {
+    /** Handler that is called when the element receives focus. */
+    onFocus?: (e: FocusEvent & {
+        currentTarget: Target;
+    }) => void;
+    /** Handler that is called when the element loses focus. */
+    onBlur?: (e: FocusEvent & {
+        currentTarget: Target;
+    }) => void;
+    /** Handler that is called when the element's focus status changes. */
+    onFocusChange?: (isFocused: boolean) => void;
+}
+export interface FocusableProps<Target extends Element = Element> extends FocusEvents<Target>, KeyboardEvents {
+    /** Whether the element should receive focus on render. */
+    autoFocus?: boolean;
+}
+export interface AriaLabelingProps {
+    /** Defines a string value that labels the current element. */
+    "aria-label"?: string;
+    /** Identifies the element (or elements) that labels the current element. */
+    "aria-labelledby"?: string;
+    /** Identifies the element (or elements) that describes the object. */
+    "aria-describedby"?: string;
+    /** Identifies the element (or elements) that provide a detailed, extended description for the object. */
+    "aria-details"?: string;
+}
+export interface AriaValidationProps {
+    /** Identifies the element that provides an error message for the object. */
+    "aria-errormessage"?: string;
+}
+/** Common DOM props allowed on any component. */
+export interface DOMProps {
+    /** The element's unique identifier. */
+    id?: string;
+}
+export interface FocusableDOMProps extends DOMProps {
+    /** Whether to exclude the element from the sequential tab order. */
+    excludeFromTabOrder?: boolean;
+}
+/** Inline style object (`style` prop of every component; render-prop form in `StyleRenderProps`). */
+export type StyleObject = Record<string, string | number | undefined>;
+export type ValidationState = "valid" | "invalid";
+export type ValidationError = string | string[];
+export interface Validation<T = unknown> {
+    /** Whether user input is required on the input before form submission. */
+    isRequired?: boolean;
+    /** Whether the input value is invalid. */
+    isInvalid?: boolean;
+    /** @deprecated upstream: use `isInvalid`. */
+    validationState?: ValidationState;
+    /** `native` blocks form submission and shows native errors; `aria` only marks the field invalid. @default "native" (RAC) */
+    validationBehavior?: "aria" | "native";
+    /** Custom validation: error message(s), or `true` / `null` / `undefined` when valid. */
+    validate?: (value: T) => ValidationError | true | null | undefined;
+}
+export interface InputBase {
+    /** Whether the input is disabled. */
+    isDisabled?: boolean;
+    /** Whether the input can be selected but not changed by the user. */
+    isReadOnly?: boolean;
+}
+/**
+ * Value props. Rivet: `value` is a plain value OR a two-way `Signal` (see `controllable`).
+ */
+export interface ValueBase<T, C = T> {
+    /** The current value (controlled): a plain value or a Signal. */
+    value?: T | import("@rivetjs/reactivity").Signal<T>;
+    /** The default value (uncontrolled). */
+    defaultValue?: T;
+    /** Handler that is called when the value changes. */
+    onChange?: (value: C) => void;
+}
+export interface TextInputBase {
+    /** Temporary text that occupies the text input when it is empty. */
+    placeholder?: string;
+}
+export interface RangeValue<T> {
+    start: T;
+    end: T;
+}
+export interface RangeInputBase<T> {
+    minValue?: T;
+    maxValue?: T;
+    step?: T;
+}
+export interface HelpTextProps {
+    /** A description for the field. */
+    description?: Content;
+    /** An error message for the field. */
+    errorMessage?: Content | ((v: ValidationResult) => Content);
+}
+export interface LabelableProps {
+    /** The content to display as the label. */
+    label?: Content;
+}

package/utils/types.js

@@ -0,0 +1 @@
+export {};

package/virtualizer/behaviour.d.ts

@@ -0,0 +1,98 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { StyleObject } from "@rivetjs/runtime/style";
+import type { Key } from "../collections/index.js";
+import { type CollectionOptions, type Node } from "./collection.js";
+import { type ScrollView } from "./dom.js";
+import type { Layout } from "./layout.js";
+import type { LayoutInfo } from "./layout-info.js";
+import type { ReusableView } from "./reusable-view.js";
+import { type VirtualizerState } from "./state.js";
+import type { Direction } from "./types.js";
+/** Key of the loader sentinel node the component appends when `isLoading` / `onLoadMore` are given. */
+export declare const LOADER_KEY = "rv-virtualizer-loader";
+/** One rendered view: JSON-serializable (server window) projection of a ReusableView + its LayoutInfo. */
+export interface VirtualView<T = unknown> {
+    /** Collection key (rows are keyed by it: kept keys keep their DOM). */
+    key: Key;
+    /** View type (`item`, `section`, `header`, `loader`, `row`, `cell`, …). */
+    type: string;
+    /** The data item (node value), or null (loaders, layout-generated views). */
+    item: T | null;
+    /** Index of the node within its parent. */
+    index: number;
+    level: number;
+    parentKey: Key | null;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Size not measured yet (the browser measures it after rendering). */
+    estimated: boolean;
+    /** Position style relative to the parent view. */
+    style: StyleObject;
+    /** Child views (sections: header + items; tables: rows / cells). */
+    children: VirtualView<T>[];
+}
+export type MaybeAccessor<T> = T | (() => T);
+/** Serializable component state. */
+export interface VirtualizerModel<T, O> {
+    id: string;
+    items: MaybeAccessor<readonly T[]>;
+    /** Layout factory (`() => new ListLayout()`), called on the server and once in the browser. */
+    layout: () => Layout<Node<T>, O>;
+    layoutOptions?: O;
+    collection: CollectionOptions<T>;
+    initialSize: {
+        width: number;
+        height: number;
+    };
+    dir?: Direction;
+    isLoading?: MaybeAccessor<boolean>;
+    onLoadMore?: () => void;
+    loadMoreOffset: number;
+    shouldObserveItemSize: boolean;
+    /** Caller-persisted keys (plus the focused view). */
+    persistedKeys: readonly Key[];
+    focusedKey: Signal<Key | null>;
+    views: Signal<VirtualView<T>[]>;
+    contentSize: Signal<{
+        width: number;
+        height: number;
+    }>;
+    isScrolling: Signal<boolean>;
+    onScroll?: (event: Event) => void;
+}
+/** Views of the engine as JSON; unchanged views keep their previous object (resumed rows stay adopted). */
+export declare function projectViews<T>(views: Iterable<ReusableView<Node<T>, unknown>>, dir: Direction | undefined, previous: Map<Key, VirtualView<T>>, parent?: LayoutInfo | null): VirtualView<T>[];
+/** First window for the server render (and client-rendered mounts): the engine at `initialSize`, scrolled to 0. */
+export declare function initialWindow<T, O>(model: VirtualizerModel<T, O>): {
+    views: VirtualView<T>[];
+    contentSize: {
+        width: number;
+        height: number;
+    };
+};
+interface Driver {
+    state: VirtualizerState<Node<unknown>, unknown>;
+    scrollView: ScrollView;
+    loadingMore: boolean;
+    lastItems: unknown;
+}
+/** The browser driver of `model` (created on first use: engine, scroll view, measurement). */
+export declare function driverOf<T, O>(model: VirtualizerModel<T, O>, element?: Element | null): Driver | null;
+/** Rows of the model: the server window, or (browser) the driver's projection; reads `items` for reactivity. */
+export declare function visibleViews<T, O>(model: VirtualizerModel<T, O>): VirtualView<T>[];
+/** Keys of `views`: the rows' `For` items. Keys keep their identity across windows, so resumed server rows are
+ * adopted and kept (a `For` re-creates an adopted row whose item changed; view descriptors change on every move). */
+export declare const viewKeys: <T>(views: readonly VirtualView<T>[]) => Key[];
+/** The view with `key` in `views` (a row's descriptor); a row being removed keeps its last descriptor. */
+export declare function viewOf<T, O>(model: VirtualizerModel<T, O>, views: readonly VirtualView<T>[], key: Key): VirtualView<T>;
+/** Scroll handler of the scroller: drive the engine, load more near the end, then the caller's `onScroll`. */
+export declare function virtualizerScroll<T, O>(model: VirtualizerModel<T, O>, event: Event): void;
+/** focusin: the focused view stays rendered (persisted) while scrolled out of view. */
+export declare function virtualizerFocusIn<T, O>(model: VirtualizerModel<T, O>, event: FocusEvent): void;
+/** Style of the content element (size of the scrollable content; no pointer events while scrolling). */
+export declare function contentStyle<T, O>(model: VirtualizerModel<T, O>): StyleObject;
+/** Style of the scroller: overflow per scroll direction, padding reset (padding is done by the layout). */
+export declare function scrollerStyle(scrollDirection: "horizontal" | "vertical" | "both"): StyleObject;
+export {};