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

package/utils/dom.d.ts

@@ -0,0 +1,85 @@
+import { type Signal } from "@rivetjs/reactivity";
+/**
+ * `CSS.escape(value)` (CSSOM "serialize an identifier"): the native one when the global `CSS` exists, else the same
+ * algorithm in JS. React Aria calls `CSS.escape` directly; environments without the global (happy-dom / jsdom set it on
+ * `window` only, older embedded webviews) would throw inside an event handler, so every cdk selector goes through this.
+ */
+export declare function cssEscape(value: string): string;
+/** Type guard: a DOM Node (has a numeric `nodeType`). */
+export declare function isNode(value: unknown): value is Node;
+/** Type guard: a Document (`nodeType` 9). */
+export declare function isDocument(value: unknown): value is Document;
+/** Type guard: a ShadowRoot (document fragment with a `host`). */
+export declare function isShadowRoot(value: unknown): value is ShadowRoot;
+/** The document `target` belongs to (window → its document; iframe content → the iframe's document). */
+export declare const getOwnerDocument: (target?: EventTarget | null) => Document;
+/** The window `target` belongs to. */
+export declare const getOwnerWindow: (target?: EventTarget | null) => Window & typeof globalThis;
+/** Attach `listener` to one or several targets; returns the cleanup. Null target / listener → no-op. */
+export declare function addEvent(target: EventTarget | EventTarget[] | null | undefined, event: string, listener?: ((event: any) => unknown) | null, options?: boolean | AddEventListenerOptions): () => void;
+/** Set a CSS property (with optional priority) on element(s); the cleanup restores each previous value. */
+export declare function setStyle(target: HTMLElement | HTMLElement[] | null, property: string, value: string, priority?: string): () => void;
+/** Shadow-DOM-safe `node.contains(otherNode)`: crosses shadow roots (via `host`) and slots. */
+export declare function nodeContains(node: Node | null | undefined, otherNode: Node | EventTarget | null | undefined): boolean;
+/** Shadow-DOM-safe `document.activeElement` (descends into open shadow roots). */
+export declare const getActiveElement: (doc?: Document) => Element | null;
+/** Shadow-DOM-safe `event.target`: the node inside an open shadow root when the listener is outside it. */
+export declare function getEventTarget<T extends EventTarget = EventTarget>(event: Event): T | null;
+/**
+ * Targets a listener must be attached to so it sees an event globally from `from`: `[to, …shadow
+ * roots between from and to]` (`to` defaults to `from`'s window; `null` → none).
+ */
+export declare function getPropagationTargets(from: Element | null | undefined, to?: Document | Window | Element | null): EventTarget[];
+/** Shadow-DOM-safe fast `node.contains(document.activeElement)`. */
+export declare function isFocusWithin(node: Element | null | undefined): boolean;
+/** Whether `node` scrolls (`overflow: auto|scroll`; the root unless `overflow: hidden`), optionally only when it overflows. */
+export declare function isScrollable(node: Element | null, checkForOverflow?: boolean): boolean;
+/** The nearest scrolling ancestor of `node` (excluding `node` itself when it scrolls), else the document scroller. */
+export declare function getScrollParent(node: Element, checkForOverflow?: boolean): Element;
+/** Every scrolling ancestor of `node` (itself included), up to and including the root when it scrolls. */
+export declare function getScrollParents(node: Element, checkForOverflow?: boolean): Element[];
+export interface ScrollIntoViewOpts {
+    /** Alignment along the block axis (default `nearest`). */
+    block?: ScrollLogicalPosition;
+    /** Alignment along the inline axis (default `nearest`). */
+    inline?: ScrollLogicalPosition;
+}
+/**
+ * Scrolls `scrollView` so that `element` is visible, like `element.scrollIntoView({ block:
+ * "nearest" })` but without scrolling the parents above `scrollView`. Honours scroll-margin,
+ * scroll-padding, borders and scrollbars (RTL: scrollbar on the left; iOS WebKit: always right).
+ */
+export declare function scrollIntoView(scrollView: HTMLElement, element: HTMLElement, opts?: ScrollIntoViewOpts): void;
+/** `scrollIntoView` for an arbitrary rectangle `target` of `element` (client coordinates). */
+export declare function scrollRectIntoView(scrollView: HTMLElement, element: HTMLElement, target: DOMRect, opts?: ScrollIntoViewOpts): void;
+export interface ScrollIntoViewportOpts {
+    /** Containing element centered in the viewport first when the target is not fully visible. */
+    containingElement?: Element | null;
+}
+/**
+ * Scrolls `targetElement` into the viewport. When the page itself cannot scroll (`overflow: hidden`
+ * on the root, e.g. under a modal), only the target's scroll parents scroll, never the body.
+ * `containingElement` (a listbox for an option, say) is centered first if the target moved.
+ */
+export declare function scrollIntoViewport(targetElement: Element | null, opts?: ScrollIntoViewportOpts): void;
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+/** Viewport size without the scrollbar, unaffected by pinch zoom (visualViewport where available). Server: 0 × 0. */
+export declare function getViewportSize(win?: (Window & typeof globalThis) | undefined): ViewportSize;
+/**
+ * react-aria `useViewportSize`: a signal of the viewport size, updated on (visual viewport) resize,
+ * ignoring updates while pinch-zoomed. Server: `{ width: 0, height: 0 }` and no listeners. Returns
+ * the signal and the cleanup; call from a client effect.
+ */
+export declare function viewportSize(win?: (Window & typeof globalThis) | undefined): {
+    size: Signal<ViewportSize>;
+    dispose: () => void;
+};
+/** Content of `<meta name|property="key">` (`csp-nonce`: also its `nonce`, then `__webpack_nonce__`). */
+export declare function getMetaValue(key: string, doc?: Document): string | undefined;
+/** Reset the cached nonce value (tests). */
+export declare function resetNonceCache(): void;
+/** The CSP nonce (`<meta property="csp-nonce">` or `__webpack_nonce__`) for injected `<style>` elements; cached per document once found. */
+export declare function getNonce(doc?: Document): string | undefined;

package/utils/dom.js

@@ -0,0 +1,402 @@
+// DOM helpers: owner document / window, shadow-DOM-safe queries, scroll parents, scrolling into
+// view, viewport size, CSP nonce.
+// Ported from react-spectrum packages/react-aria/src/utils/{domHelpers,getScrollParent,
+// getScrollParents,isScrollable,scrollIntoView,useViewportSize,getMetaValue,getNonce}.ts and
+// shadowdom/DOMFunctions.ts (Apache-2.0, © Adobe).
+//
+// react-aria gates its shadow-DOM-aware variants behind the `shadowDOM()` feature flag; here they
+// are always on (in the light DOM they behave like the plain versions). Server-safe where it makes
+// sense (owner document / window fall back to `undefined`); everything else is browser-only.
+import { signal } from "@rivetjs/reactivity";
+import { isIOS, isWebKit } from "../platform/index.js";
+/**
+ * `CSS.escape(value)` (CSSOM "serialize an identifier"): the native one when the global `CSS` exists, else the same
+ * algorithm in JS. React Aria calls `CSS.escape` directly; environments without the global (happy-dom / jsdom set it on
+ * `window` only, older embedded webviews) would throw inside an event handler, so every cdk selector goes through this.
+ */
+export function cssEscape(value) {
+    const native = globalThis.CSS;
+    if (native && typeof native.escape === "function")
+        return native.escape(value);
+    const string = String(value);
+    const length = string.length;
+    const first = string.charCodeAt(0);
+    let result = "";
+    for (let index = 0; index < length; index++) {
+        const code = string.charCodeAt(index);
+        if (code === 0x0000)
+            result += "�";
+        else if ((code >= 0x0001 && code <= 0x001f) ||
+            code === 0x007f ||
+            (index === 0 && code >= 0x0030 && code <= 0x0039) ||
+            (index === 1 && code >= 0x0030 && code <= 0x0039 && first === 0x002d))
+            result += "\\" + code.toString(16) + " ";
+        else if (index === 0 && length === 1 && code === 0x002d)
+            result += "\\" + string.charAt(index);
+        else if (code >= 0x0080 ||
+            code === 0x002d ||
+            code === 0x005f ||
+            (code >= 0x0030 && code <= 0x0039) ||
+            (code >= 0x0041 && code <= 0x005a) ||
+            (code >= 0x0061 && code <= 0x007a))
+            result += string.charAt(index);
+        else
+            result += "\\" + string.charAt(index);
+    }
+    return result;
+}
+/** Type guard: a DOM Node (has a numeric `nodeType`). */
+export function isNode(value) {
+    return value !== null && typeof value === "object" && "nodeType" in value && typeof value.nodeType === "number";
+}
+function isWindow(value) {
+    return typeof value === "object" && value != null && "window" in value && value.window === value;
+}
+/** Type guard: a Document (`nodeType` 9). */
+export function isDocument(value) {
+    return isNode(value) && value.nodeType === 9;
+}
+/** Type guard: a ShadowRoot (document fragment with a `host`). */
+export function isShadowRoot(value) {
+    return isNode(value) && value.nodeType === 11 && "host" in value;
+}
+/** The document `target` belongs to (window → its document; iframe content → the iframe's document). */
+export const getOwnerDocument = (target) => {
+    if (isWindow(target))
+        return target.document;
+    if (isDocument(target))
+        return target;
+    return target?.ownerDocument ?? (typeof document !== "undefined" ? document : undefined);
+};
+/** The window `target` belongs to. */
+export const getOwnerWindow = (target) => {
+    const ownerDocument = getOwnerDocument(target);
+    return (ownerDocument?.defaultView ?? (typeof window !== "undefined" ? window : undefined));
+};
+/** Attach `listener` to one or several targets; returns the cleanup. Null target / listener → no-op. */
+export function addEvent(target, event, listener, options) {
+    if (listener == null || target == null)
+        return () => { };
+    const targets = Array.isArray(target) ? target : [target];
+    for (const t of targets)
+        t.addEventListener(event, listener, options);
+    return () => {
+        for (const t of targets)
+            t.removeEventListener(event, listener, options);
+    };
+}
+/** Set a CSS property (with optional priority) on element(s); the cleanup restores each previous value. */
+export function setStyle(target, property, value, priority) {
+    if (target == null)
+        return () => { };
+    const restore = [];
+    for (const el of Array.isArray(target) ? target : [target]) {
+        const initialValue = el.style.getPropertyValue(property);
+        const initialPriority = el.style.getPropertyPriority(property);
+        el.style.setProperty(property, value, priority);
+        restore.unshift(() => {
+            if (initialValue)
+                el.style.setProperty(property, initialValue, initialPriority);
+            else
+                el.style.removeProperty(property);
+        });
+    }
+    return () => {
+        for (const cleanup of restore)
+            cleanup();
+    };
+}
+/** Shadow-DOM-safe `node.contains(otherNode)`: crosses shadow roots (via `host`) and slots. */
+export function nodeContains(node, otherNode) {
+    if (!node || !otherNode || !isNode(otherNode))
+        return false;
+    let current = otherNode;
+    while (current != null) {
+        if (current === node)
+            return true;
+        const slotted = current;
+        if (typeof slotted.assignedElements !== "function" && slotted.assignedSlot?.parentNode)
+            current = slotted.assignedSlot.parentNode;
+        else if (isShadowRoot(current))
+            current = current.host;
+        else
+            current = current.parentNode;
+    }
+    return false;
+}
+/** Shadow-DOM-safe `document.activeElement` (descends into open shadow roots). */
+export const getActiveElement = (doc = document) => {
+    let active = doc.activeElement;
+    while (active && "shadowRoot" in active && active.shadowRoot?.activeElement)
+        active = active.shadowRoot.activeElement;
+    return active;
+};
+/** Shadow-DOM-safe `event.target`: the node inside an open shadow root when the listener is outside it. */
+export function getEventTarget(event) {
+    const target = event.target;
+    if (typeof Element !== "undefined" && target instanceof Element && target.shadowRoot && "composedPath" in event)
+        return (event.composedPath()[0] ?? null);
+    return target;
+}
+/**
+ * Targets a listener must be attached to so it sees an event globally from `from`: `[to, …shadow
+ * roots between from and to]` (`to` defaults to `from`'s window; `null` → none).
+ */
+export function getPropagationTargets(from, to) {
+    if (to === null)
+        return [];
+    const destination = to ?? getOwnerWindow(from);
+    const targets = [destination];
+    if (!from || from === destination)
+        return targets;
+    const toRoot = "getRootNode" in destination ? destination.getRootNode() : null;
+    let current = from.getRootNode() ?? null;
+    while (isShadowRoot(current) && current !== toRoot) {
+        targets.push(current);
+        current = current.host.getRootNode();
+    }
+    return targets;
+}
+/** Shadow-DOM-safe fast `node.contains(document.activeElement)`. */
+export function isFocusWithin(node) {
+    if (!node)
+        return false;
+    const root = node.getRootNode();
+    const win = getOwnerWindow(node);
+    if (!(root instanceof win.Document || root instanceof win.ShadowRoot))
+        return false;
+    const active = root.activeElement;
+    return active != null && node.contains(active);
+}
+const scrollingRoot = (doc) => doc.scrollingElement || doc.documentElement;
+/** Whether `node` scrolls (`overflow: auto|scroll`; the root unless `overflow: hidden`), optionally only when it overflows. */
+export function isScrollable(node, checkForOverflow) {
+    if (!node)
+        return false;
+    const win = getOwnerWindow(node);
+    const style = win.getComputedStyle(node);
+    const root = scrollingRoot(node.ownerDocument);
+    let scrollable = /(auto|scroll)/.test(style.overflow + style.overflowX + style.overflowY);
+    // The root has `visible` overflow by default but scrolls nonetheless.
+    if (node === root && style.overflow !== "hidden")
+        scrollable = true;
+    if (scrollable && checkForOverflow)
+        scrollable = node.scrollHeight !== node.clientHeight || node.scrollWidth !== node.clientWidth;
+    return scrollable;
+}
+/** The nearest scrolling ancestor of `node` (excluding `node` itself when it scrolls), else the document scroller. */
+export function getScrollParent(node, checkForOverflow) {
+    let scrollable = node;
+    if (isScrollable(scrollable, checkForOverflow))
+        scrollable = scrollable.parentElement;
+    while (scrollable && !isScrollable(scrollable, checkForOverflow))
+        scrollable = scrollable.parentElement;
+    return scrollable || scrollingRoot(node.ownerDocument);
+}
+/** Every scrolling ancestor of `node` (itself included), up to and including the root when it scrolls. */
+export function getScrollParents(node, checkForOverflow) {
+    const parents = [];
+    const root = scrollingRoot(node.ownerDocument);
+    let current = node;
+    while (current) {
+        if (isScrollable(current, checkForOverflow))
+            parents.push(current);
+        if (current === root)
+            break;
+        current = current.parentElement;
+    }
+    return parents;
+}
+/**
+ * Scrolls `scrollView` so that `element` is visible, like `element.scrollIntoView({ block:
+ * "nearest" })` but without scrolling the parents above `scrollView`. Honours scroll-margin,
+ * scroll-padding, borders and scrollbars (RTL: scrollbar on the left; iOS WebKit: always right).
+ */
+export function scrollIntoView(scrollView, element, opts = {}) {
+    if (scrollView === element)
+        return;
+    scrollRectIntoView(scrollView, element, element.getBoundingClientRect(), opts);
+}
+/** `scrollIntoView` for an arbitrary rectangle `target` of `element` (client coordinates). */
+export function scrollRectIntoView(scrollView, element, target, opts = {}) {
+    const { block = "nearest", inline = "nearest" } = opts;
+    const win = getOwnerWindow(scrollView);
+    let y = scrollView.scrollTop;
+    let x = scrollView.scrollLeft;
+    const view = scrollView.getBoundingClientRect();
+    const itemStyle = win.getComputedStyle(element);
+    const viewStyle = win.getComputedStyle(scrollView);
+    const root = scrollingRoot(scrollView.ownerDocument);
+    const isRoot = scrollView === root;
+    const viewTop = isRoot ? 0 : view.top;
+    const viewBottom = isRoot ? scrollView.clientHeight : view.bottom;
+    const viewLeft = isRoot ? 0 : view.left;
+    const viewRight = isRoot ? scrollView.clientWidth : view.right;
+    const px = (v) => parseFloat(v ?? "") || 0;
+    const scrollMarginTop = px(itemStyle.scrollMarginTop);
+    const scrollMarginBottom = px(itemStyle.scrollMarginBottom);
+    const scrollMarginLeft = px(itemStyle.scrollMarginLeft);
+    const scrollMarginRight = px(itemStyle.scrollMarginRight);
+    const scrollPaddingTop = px(viewStyle.scrollPaddingTop);
+    const scrollPaddingBottom = px(viewStyle.scrollPaddingBottom);
+    const scrollPaddingLeft = px(viewStyle.scrollPaddingLeft);
+    const scrollPaddingRight = px(viewStyle.scrollPaddingRight);
+    const borderTopWidth = px(viewStyle.borderTopWidth);
+    const borderBottomWidth = px(viewStyle.borderBottomWidth);
+    const borderLeftWidth = px(viewStyle.borderLeftWidth);
+    const borderRightWidth = px(viewStyle.borderRightWidth);
+    const scrollAreaTop = target.top - scrollMarginTop;
+    const scrollAreaBottom = target.bottom + scrollMarginBottom;
+    const scrollAreaLeft = target.left - scrollMarginLeft;
+    const scrollAreaRight = target.right + scrollMarginRight;
+    const scrollBarOffsetX = isRoot ? 0 : borderLeftWidth + borderRightWidth;
+    const scrollBarOffsetY = isRoot ? 0 : borderTopWidth + borderBottomWidth;
+    const scrollBarWidth = isRoot ? 0 : scrollView.offsetWidth - scrollView.clientWidth - scrollBarOffsetX;
+    const scrollBarHeight = isRoot ? 0 : scrollView.offsetHeight - scrollView.clientHeight - scrollBarOffsetY;
+    const scrollPortTop = viewTop + (isRoot ? 0 : borderTopWidth) + scrollPaddingTop;
+    const scrollPortBottom = viewBottom - (isRoot ? 0 : borderBottomWidth) - scrollPaddingBottom - scrollBarHeight;
+    let scrollPortLeft = viewLeft + (isRoot ? 0 : borderLeftWidth) + scrollPaddingLeft;
+    let scrollPortRight = viewRight - (isRoot ? 0 : borderRightWidth) - scrollPaddingRight;
+    // WebKit on iOS always positions the scrollbar on the right.
+    if ((isIOS() && isWebKit()) || viewStyle.direction === "ltr")
+        scrollPortRight -= scrollBarWidth;
+    else if (viewStyle.direction === "rtl")
+        scrollPortLeft += scrollBarWidth;
+    const shouldScrollBlock = scrollAreaTop < scrollPortTop || scrollAreaBottom > scrollPortBottom;
+    const shouldScrollInline = scrollAreaLeft < scrollPortLeft || scrollAreaRight > scrollPortRight;
+    if (shouldScrollBlock && block === "start")
+        y += scrollAreaTop - scrollPortTop;
+    else if (shouldScrollBlock && block === "center")
+        y += (scrollAreaTop + scrollAreaBottom) / 2 - (scrollPortTop + scrollPortBottom) / 2;
+    else if (shouldScrollBlock && block === "end")
+        y += scrollAreaBottom - scrollPortBottom;
+    else if (shouldScrollBlock && block === "nearest") {
+        const start = scrollAreaTop - scrollPortTop;
+        const end = scrollAreaBottom - scrollPortBottom;
+        y += Math.abs(start) <= Math.abs(end) ? start : end;
+    }
+    if (shouldScrollInline && inline === "start")
+        x += scrollAreaLeft - scrollPortLeft;
+    else if (shouldScrollInline && inline === "center")
+        x += (scrollAreaLeft + scrollAreaRight) / 2 - (scrollPortLeft + scrollPortRight) / 2;
+    else if (shouldScrollInline && inline === "end")
+        x += scrollAreaRight - scrollPortRight;
+    else if (shouldScrollInline && inline === "nearest") {
+        const start = scrollAreaLeft - scrollPortLeft;
+        const end = scrollAreaRight - scrollPortRight;
+        x += Math.abs(start) <= Math.abs(end) ? start : end;
+    }
+    if (typeof scrollView.scrollTo === "function")
+        scrollView.scrollTo({ left: x, top: y });
+    else {
+        scrollView.scrollLeft = x;
+        scrollView.scrollTop = y;
+    }
+}
+/**
+ * Scrolls `targetElement` into the viewport. When the page itself cannot scroll (`overflow: hidden`
+ * on the root, e.g. under a modal), only the target's scroll parents scroll, never the body.
+ * `containingElement` (a listbox for an option, say) is centered first if the target moved.
+ */
+export function scrollIntoViewport(targetElement, opts = {}) {
+    const { containingElement } = opts;
+    if (!targetElement || !targetElement.isConnected)
+        return;
+    const doc = targetElement.ownerDocument;
+    const root = scrollingRoot(doc);
+    const isScrollPrevented = getOwnerWindow(targetElement).getComputedStyle(root).overflow === "hidden";
+    const { left: originalLeft, top: originalTop } = targetElement.getBoundingClientRect();
+    if (!isScrollPrevented) {
+        // scrollIntoView, not focus(): focus does not scroll an already focused or partly visible element.
+        targetElement.scrollIntoView?.({ block: "nearest" });
+        const { left: newLeft, top: newTop } = targetElement.getBoundingClientRect();
+        // Account for sub pixel differences from rounding.
+        if (Math.abs(originalLeft - newLeft) > 1 || Math.abs(originalTop - newTop) > 1) {
+            containingElement?.scrollIntoView?.({ block: "center", inline: "center" });
+            targetElement.scrollIntoView?.({ block: "nearest" });
+        }
+    }
+    else {
+        // The target's scroll parents are walked once (a `getComputedStyle` per ancestor; scrolling does not change them).
+        const targetParents = getScrollParents(targetElement, true);
+        for (const parent of targetParents)
+            scrollIntoView(parent, targetElement);
+        const { left: newLeft, top: newTop } = targetElement.getBoundingClientRect();
+        if (Math.abs(originalLeft - newLeft) > 1 || Math.abs(originalTop - newTop) > 1) {
+            const scrollParents = containingElement ? getScrollParents(containingElement, true) : [];
+            for (const parent of scrollParents)
+                scrollIntoView(parent, containingElement, { block: "center", inline: "center" });
+            for (const parent of targetParents)
+                scrollIntoView(parent, targetElement);
+        }
+    }
+}
+/** Viewport size without the scrollbar, unaffected by pinch zoom (visualViewport where available). Server: 0 × 0. */
+export function getViewportSize(win = typeof window === "undefined" ? undefined : window) {
+    if (!win)
+        return { width: 0, height: 0 };
+    const vv = win.visualViewport;
+    const docEl = win.document.documentElement;
+    return {
+        // The visual viewport width may include the scrollbar gutter: take the smaller one.
+        width: vv ? Math.min(vv.width * vv.scale, docEl.clientWidth) : docEl.clientWidth,
+        height: vv ? vv.height * vv.scale : docEl.clientHeight,
+    };
+}
+/**
+ * react-aria `useViewportSize`: a signal of the viewport size, updated on (visual viewport) resize,
+ * ignoring updates while pinch-zoomed. Server: `{ width: 0, height: 0 }` and no listeners. Returns
+ * the signal and the cleanup; call from a client effect.
+ */
+export function viewportSize(win = typeof window === "undefined" ? undefined : window) {
+    const size = signal(getViewportSize(win));
+    if (!win)
+        return { size, dispose: () => { } };
+    const vv = win.visualViewport;
+    const update = (next) => {
+        const current = size();
+        if (next.width !== current.width || next.height !== current.height)
+            size.set(next);
+    };
+    const onResize = () => {
+        if (vv && vv.scale > 1)
+            return;
+        update(getViewportSize(win));
+    };
+    const target = vv ?? win;
+    target.addEventListener("resize", onResize);
+    return { size, dispose: () => target.removeEventListener("resize", onResize) };
+}
+/** Content of `<meta name|property="key">` (`csp-nonce`: also its `nonce`, then `__webpack_nonce__`). */
+export function getMetaValue(key, doc) {
+    const win = getOwnerWindow(doc);
+    const ownerDocument = getOwnerDocument(doc);
+    if (ownerDocument == null || win == null)
+        return;
+    let content;
+    const meta = ownerDocument.querySelector(`meta[name="${cssEscape(key)}"], meta[property="${cssEscape(key)}"]`);
+    if (meta && meta instanceof win.HTMLMetaElement) {
+        if (key === "csp-nonce" && meta.nonce)
+            content ??= meta.nonce || undefined;
+        if (meta.content)
+            content ??= meta.content || undefined;
+    }
+    if (key === "csp-nonce")
+        content ??=
+            win.__webpack_nonce__ || globalThis.__webpack_nonce__ || undefined;
+    return content;
+}
+let nonceCache = new WeakMap();
+/** Reset the cached nonce value (tests). */
+export function resetNonceCache() {
+    nonceCache = new WeakMap();
+}
+/** The CSP nonce (`<meta property="csp-nonce">` or `__webpack_nonce__`) for injected `<style>` elements; cached per document once found. */
+export function getNonce(doc) {
+    const ownerDocument = getOwnerDocument(doc);
+    let nonce = nonceCache.get(ownerDocument);
+    nonce ??= getMetaValue("csp-nonce", ownerDocument);
+    if (nonce !== undefined)
+        nonceCache.set(ownerDocument, nonce);
+    return nonce;
+}

package/utils/id.d.ts

@@ -0,0 +1,23 @@
+import { type Signal } from "@rivetjs/reactivity";
+export { createId, withIdScope } from "@rivetjs/runtime/id";
+/** If a default is not provided, generate an id (react-aria `useId`). */
+export declare function useId(defaultId?: string): string;
+/**
+ * A reactive id (`useId` whose value `mergeIds` can change): `defaultId` or a new id. Bindings
+ * reading it update when a `mergeIds` call merges this id into another one.
+ */
+export declare function idSignal(defaultId?: string): Signal<string>;
+/** Forget the reactive ids registered for `id` (react-aria's cleanup when the id unmounts). */
+export declare function releaseId(id: string): void;
+/**
+ * Merges two ids. Equal → that id. Otherwise the reactive ids (`idSignal`) holding `idA` switch to
+ * `idB` (result `idB`), else those holding `idB` switch to `idA` (result `idA`), else `idB`.
+ */
+export declare function mergeIds(idA: string, idB: string): string;
+/**
+ * react-aria `useSlotId`: `id` when an element with that id is rendered in `root`'s document, else
+ * undefined — so `aria-describedby={slotId}` never points at a missing element. Rivet: call it in a
+ * client effect / handler after the slot rendered (server: returns `id`, as the server renders the
+ * slot in the same pass and React's first render does the same).
+ */
+export declare function useSlotId(id: string, root?: Node | null): string | undefined;

package/utils/id.js

@@ -0,0 +1,100 @@
+// SSR-stable unique ids: `createId` / `withIdScope` re-export `@rivetjs/runtime/id` (server `rv…`,
+// browser `rvc…`). Plus react-aria's id utilities.
+// Ported from react-spectrum packages/react-aria/src/utils/useId.ts (Apache-2.0, © Adobe):
+// `useId`, `mergeIds`, `useSlotId`.
+//
+// Rivet: no hydration, so an id only has to be unique in the document — there is no SSR id
+// matching to do and `useId(defaultId)` is `defaultId ?? createId()`. React re-renders components
+// whose id lost a `mergeIds`; Rivet components that need that read an `idSignal()` (reactive id),
+// which `mergeIds` updates the same way the original updates its `idsUpdaterMap` refs.
+import { signal } from "@rivetjs/reactivity";
+import { createId } from "@rivetjs/runtime/id";
+import { idScoping, scopedIdUpdaters } from "#server";
+export { createId, withIdScope } from "@rivetjs/runtime/id";
+/** If a default is not provided, generate an id (react-aria `useId`). */
+export function useId(defaultId) {
+    return defaultId || createId();
+}
+const updaters = new Map();
+const SWEEP = 1024;
+let sweepAt = SWEEP;
+const registry = () => (idScoping && scopedIdUpdaters()) || updaters;
+/**
+ * A reactive id (`useId` whose value `mergeIds` can change): `defaultId` or a new id. Bindings
+ * reading it update when a `mergeIds` call merges this id into another one.
+ */
+export function idSignal(defaultId) {
+    const id = useId(defaultId);
+    const value = signal(id);
+    const map = registry();
+    const refs = map.get(id);
+    if (refs) {
+        refs.push(new WeakRef(value));
+        // Same id re-created over and over (a fixed `id` prop remounted): prune its list at powers of two.
+        if (refs.length >= 8 && (refs.length & (refs.length - 1)) === 0)
+            prune(map, id, refs);
+    }
+    else {
+        map.set(id, [new WeakRef(value)]);
+        if (map === updaters && updaters.size >= sweepAt) {
+            for (const [key, list] of updaters)
+                prune(updaters, key, list);
+            sweepAt = Math.max(SWEEP, updaters.size * 2);
+        }
+    }
+    return value;
+}
+function prune(map, id, refs) {
+    let n = 0;
+    for (let i = 0; i < refs.length; i++)
+        if (refs[i].deref() !== undefined)
+            refs[n++] = refs[i];
+    if (n === 0)
+        map.delete(id);
+    else
+        refs.length = n;
+}
+/** Forget the reactive ids registered for `id` (react-aria's cleanup when the id unmounts). */
+export function releaseId(id) {
+    registry().delete(id);
+}
+/**
+ * Merges two ids. Equal → that id. Otherwise the reactive ids (`idSignal`) holding `idA` switch to
+ * `idB` (result `idB`), else those holding `idB` switch to `idA` (result `idA`), else `idB`.
+ */
+export function mergeIds(idA, idB) {
+    if (idA === idB)
+        return idA;
+    const setA = live(idA);
+    if (setA) {
+        for (const ref of setA)
+            ref.set(idB);
+        return idB;
+    }
+    const setB = live(idB);
+    if (setB) {
+        for (const ref of setB)
+            ref.set(idA);
+        return idA;
+    }
+    return idB;
+}
+function live(id) {
+    const list = registry()
+        .get(id)
+        ?.map((ref) => ref.deref())
+        .filter((s) => !!s);
+    return list?.length ? list : undefined;
+}
+/**
+ * react-aria `useSlotId`: `id` when an element with that id is rendered in `root`'s document, else
+ * undefined — so `aria-describedby={slotId}` never points at a missing element. Rivet: call it in a
+ * client effect / handler after the slot rendered (server: returns `id`, as the server renders the
+ * slot in the same pass and React's first render does the same).
+ */
+export function useSlotId(id, root) {
+    const doc = root ? (root.ownerDocument ?? root) : typeof document === "undefined" ? undefined : document;
+    if (!doc)
+        return id;
+    return doc.getElementById(id) ? id : undefined;
+}

package/utils/index.d.ts

@@ -0,0 +1,57 @@
+import { type Disposer } from "@rivetjs/reactivity";
+export { chain, mergeProps, mergeRefs, type RefLike } from "../interactions/merge-props.jsx";
+/** Focus `element` without scrolling it into view (`focus({ preventScroll: true })`, Baseline). */
+export declare function focusWithoutScrolling(element: HTMLElement | SVGElement): void;
+/** Offset of an element edge in client coordinates: left/top, or right/bottom when `reverse`. */
+export declare function getOffset(element: Element, reverse?: boolean, orientation?: "horizontal" | "vertical"): number;
+/** Clamps `value` into [min, max]. */
+export declare function clamp(value: number, min?: number, max?: number): number;
+/** Rounds `value` to the decimal precision of `step` (exponent notation steps included). */
+export declare function roundToStepPrecision(value: number, step: number): number;
+/** Snaps `value` to the nearest multiple of `step` from `min` (react-stately `snapValueToStep`), then clamps. */
+export declare function snapValueToStep(value: number, min: number | undefined, max: number | undefined, step: number): number;
+/** Rounds `value` to `digits` digits in `base`. */
+export declare function toFixedNumber(value: number, digits: number, base?: number): number;
+/**
+ * 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;
+export interface LabelingProps {
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}
+/**
+ * react-aria `useLabels`: with both `aria-label` and `aria-labelledby`, the element labels itself too
+ * (its own id joins `aria-labelledby`, so both are read); id lists are normalized; without any label
+ * `defaultLabel` becomes `aria-label`. Pure (an `id` is created when missing).
+ */
+export declare function useLabels(props: LabelingProps, defaultLabel?: string): LabelingProps;
+/**
+ * react-aria `useDescription`: a shared hidden element holding `description` (one per distinct text,
+ * reference counted) for `aria-describedby`. Browser only: call from a client effect / handler with
+ * the element to describe; returns the cleanup (removes the attribute, drops the shared node when
+ * unused). Server-rendered markup should render its own description element instead.
+ */
+export declare function useDescription(element: Element, description?: string): () => void;
+/**
+ * react-aria `useFormReset`: when the field's form resets (and the reset was not cancelled), call
+ * `onReset(initialValue)`. Returns the cleanup. Call from a client effect, or from the first handler
+ * that needs it (a resumed page's form reset needs no JS when the value lives in the DOM).
+ */
+export declare function useFormReset<T>(field: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null | undefined, initialValue: T, onReset: (value: T) => void): () => void;
+/**
+ * react-aria `useUpdateEffect`: run `fn` when `deps()` changes after the first run (the first run only
+ * subscribes). Values compare with `Object.is` per position. Returns the disposer.
+ */
+export declare function updateEffect(deps: () => readonly unknown[], fn: () => void | (() => void)): Disposer;
+export { renderElement, type DOMRenderFunction, type DOMRenderProps } from "./render.js";