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

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,43 @@
+import { type Disposer } from "@rivetjs/reactivity";
+export { chain, mergeProps, mergeRefs, type RefLike } from "../interactions/merge-props.jsx";
+export { _resetTransitions, focusWithoutScrolling, runAfterTransition, trackTransitions } from "./transitions.js";
+/** 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;
+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";

package/utils/index.js

@@ -0,0 +1,160 @@
+// react-aria utilities.
+// Ported from react-spectrum packages/react-aria/src/utils (Apache-2.0, © Adobe): chain, mergeProps,
+// mergeRefs, runAfterTransition, focusWithoutScrolling, getOffset, useLabels, useDescription,
+// useFormReset, useUpdateEffect; react-stately utils/number (clamp, snapValueToStep, toFixedNumber).
+//
+// `chain` / `mergeProps` / `mergeRefs` live in `../interactions/merge-props.tsx` (a resume-compiled
+// module, so chained handlers stay resumable), `focusWithoutScrolling` / `runAfterTransition` in `./transitions.ts`;
+// both are re-exported here.
+// Rivet mapping of the hooks (no hooks, no re-renders):
+// - `useLayoutEffect` / `useEffect` → `clientEffect(fn, { when })` from `@rivetjs/runtime/dom` in a
+//   component (never runs on the server, resumes at its trigger), or `effect` in browser-only code.
+// - `useUpdateEffect(cb, deps)` → `updateEffect(deps, cb)` (skips the first run).
+// - `useLabels` / `useDescription` / `useFormReset` → plain functions returning attributes, or
+//   attaching listeners from a handler / client effect, returning their cleanup.
+import { effect, untrack } from "@rivetjs/reactivity";
+import { createId } from "@rivetjs/runtime/id";
+export { chain, mergeProps, mergeRefs } from "../interactions/merge-props.jsx";
+// Leaf module (DOCS-COLD 2026-10-20): `interactions/utils.ts` imports these from there, so focus / overlay helpers
+// never reach this barrel's `merge-props` re-export (chunk owner walks follow every static import).
+export { _resetTransitions, focusWithoutScrolling, runAfterTransition, trackTransitions } from "./transitions.js";
+/** Offset of an element edge in client coordinates: left/top, or right/bottom when `reverse`. */
+export function getOffset(element, reverse, orientation = "horizontal") {
+    const rect = element.getBoundingClientRect();
+    if (reverse)
+        return orientation === "horizontal" ? rect.right : rect.bottom;
+    return orientation === "horizontal" ? rect.left : rect.top;
+}
+/** Clamps `value` into [min, max]. */
+export function clamp(value, min = -Infinity, max = Infinity) {
+    return Math.min(Math.max(value, min), max);
+}
+/** Rounds `value` to the decimal precision of `step` (exponent notation steps included). */
+export function roundToStepPrecision(value, step) {
+    let roundedValue = value;
+    let precision = 0;
+    const stepString = step.toString();
+    const eIndex = stepString.toLowerCase().indexOf("e-");
+    if (eIndex > 0)
+        precision = Math.abs(Math.floor(Math.log10(Math.abs(step)))) + eIndex;
+    else {
+        const pointIndex = stepString.indexOf(".");
+        if (pointIndex >= 0)
+            precision = stepString.length - pointIndex;
+    }
+    if (precision > 0) {
+        const pow = Math.pow(10, precision);
+        roundedValue = Math.round(roundedValue * pow) / pow;
+    }
+    return roundedValue;
+}
+/** Snaps `value` to the nearest multiple of `step` from `min` (react-stately `snapValueToStep`), then clamps. */
+export function snapValueToStep(value, min, max, step) {
+    min = Number(min);
+    max = Number(max);
+    const remainder = (value - (isNaN(min) ? 0 : min)) % step;
+    let snappedValue = roundToStepPrecision(Math.abs(remainder) * 2 >= step ? value + Math.sign(remainder) * (step - Math.abs(remainder)) : value - remainder, step);
+    if (!isNaN(min)) {
+        if (snappedValue < min)
+            snappedValue = min;
+        else if (!isNaN(max) && snappedValue > max)
+            snappedValue = min + Math.floor(roundToStepPrecision((max - min) / step, step)) * step;
+    }
+    else if (!isNaN(max) && snappedValue > max)
+        snappedValue = Math.floor(roundToStepPrecision(max / step, step)) * step;
+    return roundToStepPrecision(snappedValue, step);
+}
+/** Rounds `value` to `digits` digits in `base`. */
+export function toFixedNumber(value, digits, base = 10) {
+    const pow = Math.pow(base, digits);
+    return Math.round(value * pow) / pow;
+}
+/**
+ * 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 function useLabels(props, defaultLabel) {
+    let { id, "aria-label": label, "aria-labelledby": labelledBy } = props;
+    id = id || createId();
+    if (labelledBy && label)
+        labelledBy = [...new Set([id, ...labelledBy.trim().split(/\s+/)])].join(" ");
+    else if (labelledBy)
+        labelledBy = labelledBy.trim().split(/\s+/).join(" ");
+    if (!label && !labelledBy && defaultLabel)
+        label = defaultLabel;
+    return { id, "aria-label": label, "aria-labelledby": labelledBy };
+}
+let descriptionId = 0;
+const descriptionNodes = new Map();
+/**
+ * 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 function useDescription(element, description) {
+    if (!description)
+        return () => { };
+    const doc = element.ownerDocument;
+    let desc = descriptionNodes.get(description);
+    if (!desc || !desc.element.isConnected) {
+        const node = doc.createElement("div");
+        node.id = `rv-description-${descriptionId++}`;
+        node.style.display = "none";
+        node.textContent = description;
+        doc.body.appendChild(node);
+        desc = { refCount: 0, element: node };
+        descriptionNodes.set(description, desc);
+    }
+    desc.refCount++;
+    element.setAttribute("aria-describedby", desc.element.id);
+    const d = desc;
+    return () => {
+        if (element.getAttribute("aria-describedby") === d.element.id)
+            element.removeAttribute("aria-describedby");
+        if (--d.refCount === 0) {
+            d.element.remove();
+            descriptionNodes.delete(description);
+        }
+    };
+}
+/**
+ * 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 function useFormReset(field, initialValue, onReset) {
+    const form = field?.form;
+    if (!form)
+        return () => { };
+    const handleReset = (event) => {
+        if (onReset && !event.defaultPrevented)
+            onReset(initialValue);
+    };
+    form.addEventListener("reset", handleReset);
+    return () => form.removeEventListener("reset", handleReset);
+}
+/**
+ * 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 function updateEffect(deps, fn) {
+    let previous = null;
+    let cleanup;
+    const dispose = effect(() => {
+        const next = deps();
+        if (previous && (previous.length !== next.length || next.some((dep, i) => !Object.is(dep, previous[i])))) {
+            if (typeof cleanup === "function")
+                cleanup();
+            cleanup = untrack(fn);
+        }
+        previous = next;
+    });
+    return () => {
+        dispose();
+        if (typeof cleanup === "function")
+            cleanup();
+    };
+}
+export { renderElement } from "./render.js";

package/utils/link-state.d.ts

@@ -0,0 +1,6 @@
+/** Set while `openLink` dispatches its event (react-aria's `openLink.isOpening`); read by usePress / focus-visible / collections. */
+export declare const linkState: {
+    isOpening: boolean;
+};
+/** Whether `openLink` is dispatching its synthetic click (item click handlers let it through). */
+export declare const isOpeningLink: () => boolean;

package/utils/link-state.js

@@ -0,0 +1,6 @@
+// The flag `openLink` (`./links.tsx`) sets while it dispatches its synthetic click. A leaf module (DOCS-COLD
+// 2026-10-20): focus-visible / usePress read it through `../interactions/utils.ts` without reaching the router module.
+/** Set while `openLink` dispatches its event (react-aria's `openLink.isOpening`); read by usePress / focus-visible / collections. */
+export const linkState = { isOpening: false };
+/** Whether `openLink` is dispatching its synthetic click (item click handlers let it through). */
+export const isOpeningLink = () => linkState.isOpening;

package/utils/links.d.ts

@@ -0,0 +1,82 @@
+import type { Content, Slot } from "@rivetjs/runtime/jsx-runtime";
+export type Href = string;
+/** Options passed through to the router's `navigate` (react-aria `RouterOptions`). */
+export type RouterOptions = Record<string, unknown> | undefined;
+export interface Modifiers {
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+}
+/**
+ * The router in scope (react-aria `Router`). Rivet: plain data so handlers can capture it — the
+ * native router is `{ isNative: true }`; a `RouterProvider` router carries the user's `navigate` /
+ * `useHref` (resumable arrows). react-aria's `router.open(…)` / `router.useHref(…)` methods are the
+ * free functions `routerOpen(router, …)` / `routerHref(router, …)`.
+ */
+export interface Router {
+    /** True for the default router (plain browser / document-level router navigation). */
+    readonly isNative: boolean;
+    /** Custom navigation (`RouterProvider`); absent for the native router. */
+    readonly navigate?: (href: Href, routerOptions: RouterOptions) => void;
+    /** Maps a router href to a DOM href (`RouterProvider` `useHref`). */
+    readonly useHref?: (href: Href) => string;
+}
+export interface LinkDOMProps {
+    href?: Href;
+    hrefLang?: string;
+    target?: string;
+    rel?: string;
+    download?: boolean | string;
+    ping?: string;
+    referrerPolicy?: string;
+    routerOptions?: RouterOptions;
+}
+/** Whether a click on `link` with `modifiers` should navigate in-document (same origin, `_self`, no download, no modifier). */
+export declare function shouldClientNavigate(link: HTMLAnchorElement, modifiers: Modifiers): boolean;
+export { isOpeningLink, linkState } from "./link-state.js";
+/**
+ * Open `target` as if clicked with `modifiers` (new tab / window / download follow the browser's
+ * rules for them). Focuses the link without scrolling, then dispatches a click (WebKit on macOS:
+ * a keydown Enter, as WebKit ignores modifiers on synthetic clicks).
+ */
+export declare function openLink(target: HTMLAnchorElement, modifiers: Modifiers, setOpening?: boolean): void;
+/** Default router's `open`: a synthetic link for `target` (an `<a>`, or an element with `data-href`), opened natively. */
+export declare function openSyntheticLink(target: Element, modifiers: Modifiers): void;
+/** Context `RouterProvider` sets; default: the native router. */
+export declare const RouterContext: import("@rivetjs/reactivity").Context<Router>;
+/** The router links should use (closest `RouterProvider`, else native). Call while rendering; capture the result in handlers. */
+export declare function useRouter(): Router;
+/** Build a client-side router for `RouterProvider` / `RouterContext` from a `navigate` function. */
+export declare function createRouter(navigate: (path: Href, routerOptions: RouterOptions) => void, useHref?: (href: Href) => string): Router;
+/** react-aria `router.useHref(href)`: the DOM href (`undefined` stays `undefined`; no router = native). */
+export declare function routerHref(router: Router | undefined, href: Href | undefined): string | undefined;
+/**
+ * react-aria `router.open(target, modifiers, href, routerOptions)`: navigate `target` (an anchor, or
+ * an element with `data-href`) — through `navigate` when the click should stay in-document, else
+ * natively with the modifiers honoured. No router = native.
+ */
+export declare function routerOpen(router: Router | undefined, target: Element, modifiers: Modifiers, href: Href, routerOptions?: RouterOptions): void;
+export interface RouterProviderProps {
+    /** The client router's navigate function (an inline arrow or local function: it resumes). */
+    navigate: (path: Href, routerOptions: RouterOptions) => void;
+    /** Maps a router href to a native `href` (base paths). */
+    useHref?: (href: Href) => string;
+    /** The subtree: plain children (a lazy compiler slot rendered under the provider) or `{() => <App />}`. */
+    children?: Slot | Content;
+}
+/** Routes every link / link item in its subtree through `navigate` (react-aria `RouterProvider`). */
+export declare function RouterProvider(props: RouterProviderProps): string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined)[] | (() => string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | readonly (string | number | bigint | boolean | import("@rivetjs/runtime/jsx-runtime").CompiledElement | /*elided*/ any | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined)[] | /*elided*/ any | null | undefined) | null | undefined;
+/** Deprecated react-aria helper: `data-*` attributes describing a synthetic link (no `useHref` mapping). */
+export declare function getSyntheticLinkProps(props: LinkDOMProps): Record<string, unknown>;
+/** `data-*` attributes describing a synthetic link, `href` mapped by the router's `useHref`. */
+export declare function useSyntheticLinkProps(props: LinkDOMProps): Record<string, unknown>;
+/** `useSyntheticLinkProps` for a router captured earlier (handlers / behaviour code; `download: true` renders `""`). */
+export declare function syntheticLinkAttrs(props: LinkDOMProps, router?: Router): Record<string, string | undefined>;
+/** Link attributes present in `props` (`href` mapped by the router's `useHref`). */
+export declare function useLinkProps(props?: LinkDOMProps): LinkDOMProps;
+/**
+ * Click handler body for links rendered by a component: with a non-native router, prevent the
+ * default and let the router open the link when it should navigate in-document.
+ */
+export declare function handleLinkClick(event: MouseEvent, router: Router, href: Href | undefined, routerOptions: RouterOptions): void;

package/utils/links.jsx

@@ -0,0 +1,150 @@
+import { createContext, provide, useContext } from "@rivetjs/reactivity";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { isIPad, isMac, isWebKit } from "../platform/index.js";
+import { renderSlot } from "@rivetjs/runtime/slot";
+import { linkState } from "./link-state.js";
+/** Whether a click on `link` with `modifiers` should navigate in-document (same origin, `_self`, no download, no modifier). */
+export function shouldClientNavigate(link, modifiers) {
+    // getAttribute: Firefox defaults link.target to "_parent" inside an iframe.
+    const target = link.getAttribute("target");
+    return ((!target || target === "_self") &&
+        link.origin === link.ownerDocument.defaultView?.location.origin &&
+        !link.hasAttribute("download") &&
+        !modifiers.metaKey && // new tab (mac)
+        !modifiers.ctrlKey && // new tab (windows)
+        !modifiers.altKey && // download
+        !modifiers.shiftKey);
+}
+export { isOpeningLink, linkState } from "./link-state.js";
+/**
+ * Open `target` as if clicked with `modifiers` (new tab / window / download follow the browser's
+ * rules for them). Focuses the link without scrolling, then dispatches a click (WebKit on macOS:
+ * a keydown Enter, as WebKit ignores modifiers on synthetic clicks).
+ */
+export function openLink(target, modifiers, setOpening = true) {
+    const { metaKey, ctrlKey, altKey, shiftKey } = modifiers;
+    const view = target.ownerDocument.defaultView;
+    const event = isWebKit() && isMac() && !isIPad()
+        ? new view.KeyboardEvent("keydown", { keyIdentifier: "Enter", metaKey, ctrlKey, altKey, shiftKey })
+        : new view.MouseEvent("click", { metaKey, ctrlKey, altKey, shiftKey, detail: 1, bubbles: true, cancelable: true });
+    linkState.isOpening = setOpening;
+    target.focus({ preventScroll: true });
+    target.dispatchEvent(event);
+    linkState.isOpening = false;
+}
+function getSyntheticLink(target, open) {
+    if (target instanceof target.ownerDocument.defaultView.HTMLAnchorElement)
+        open(target);
+    else if (target.hasAttribute("data-href")) {
+        const link = target.ownerDocument.createElement("a");
+        link.href = target.getAttribute("data-href");
+        if (target.hasAttribute("data-target"))
+            link.target = target.getAttribute("data-target");
+        if (target.hasAttribute("data-rel"))
+            link.rel = target.getAttribute("data-rel");
+        if (target.hasAttribute("data-download"))
+            link.download = target.getAttribute("data-download");
+        if (target.hasAttribute("data-ping"))
+            link.ping = target.getAttribute("data-ping");
+        if (target.hasAttribute("data-referrer-policy"))
+            link.referrerPolicy = target.getAttribute("data-referrer-policy");
+        target.appendChild(link);
+        open(link);
+        target.removeChild(link);
+    }
+}
+/** Default router's `open`: a synthetic link for `target` (an `<a>`, or an element with `data-href`), opened natively. */
+export function openSyntheticLink(target, modifiers) {
+    getSyntheticLink(target, (link) => openLink(link, modifiers));
+}
+const nativeRouter = { isNative: true };
+/** Context `RouterProvider` sets; default: the native router. */
+export const RouterContext = resumableContext(createContext(nativeRouter, { id: "rv-router" }));
+/** The router links should use (closest `RouterProvider`, else native). Call while rendering; capture the result in handlers. */
+export function useRouter() {
+    return useContext(RouterContext);
+}
+/** Build a client-side router for `RouterProvider` / `RouterContext` from a `navigate` function. */
+export function createRouter(navigate, useHref) {
+    return { isNative: false, navigate, useHref };
+}
+/** react-aria `router.useHref(href)`: the DOM href (`undefined` stays `undefined`; no router = native). */
+export function routerHref(router, href) {
+    return href == null ? undefined : router?.useHref ? router.useHref(href) : href;
+}
+/**
+ * react-aria `router.open(target, modifiers, href, routerOptions)`: navigate `target` (an anchor, or
+ * an element with `data-href`) — through `navigate` when the click should stay in-document, else
+ * natively with the modifiers honoured. No router = native.
+ */
+export function routerOpen(router, target, modifiers, href, routerOptions) {
+    const navigate = router?.isNative === false ? router.navigate : undefined;
+    if (!navigate)
+        return openSyntheticLink(target, modifiers);
+    getSyntheticLink(target, (link) => {
+        if (shouldClientNavigate(link, modifiers))
+            navigate(href, routerOptions);
+        else
+            openLink(link, modifiers);
+    });
+}
+/** Routes every link / link item in its subtree through `navigate` (react-aria `RouterProvider`). */
+export function RouterProvider(props) {
+    const router = createRouter(props.navigate, props.useHref);
+    const children = props.children;
+    return provide(RouterContext, router, () => renderSlot(children));
+}
+/** Deprecated react-aria helper: `data-*` attributes describing a synthetic link (no `useHref` mapping). */
+export function getSyntheticLinkProps(props) {
+    return {
+        "data-href": props.href,
+        "data-target": props.target,
+        "data-rel": props.rel,
+        "data-download": props.download,
+        "data-ping": props.ping,
+        "data-referrer-policy": props.referrerPolicy,
+    };
+}
+/** `data-*` attributes describing a synthetic link, `href` mapped by the router's `useHref`. */
+export function useSyntheticLinkProps(props) {
+    return syntheticLinkAttrs(props, useRouter());
+}
+/** `useSyntheticLinkProps` for a router captured earlier (handlers / behaviour code; `download: true` renders `""`). */
+export function syntheticLinkAttrs(props, router) {
+    return {
+        "data-href": routerHref(router, props.href),
+        "data-target": props.target,
+        "data-rel": props.rel,
+        "data-download": props.download === true ? "" : props.download || undefined,
+        "data-ping": props.ping,
+        "data-referrer-policy": props.referrerPolicy,
+    };
+}
+/** Link attributes present in `props` (`href` mapped by the router's `useHref`). */
+export function useLinkProps(props) {
+    const router = useRouter();
+    const linkProps = {};
+    if (props)
+        for (const key of ["href", "target", "rel", "download", "ping", "referrerPolicy"])
+            if (key in props && props[key] !== undefined)
+                linkProps[key] = key === "href" ? routerHref(router, props.href) : props[key];
+    return linkProps;
+}
+/**
+ * Click handler body for links rendered by a component: with a non-native router, prevent the
+ * default and let the router open the link when it should navigate in-document.
+ */
+export function handleLinkClick(event, router, href, routerOptions) {
+    const link = event.currentTarget;
+    if (!router.isNative &&
+        link &&
+        link instanceof link.ownerDocument.defaultView.HTMLAnchorElement &&
+        link.href &&
+        // A router Link component may already have prevented the default.
+        !event.defaultPrevented &&
+        shouldClientNavigate(link, event) &&
+        href) {
+        event.preventDefault();
+        routerOpen(router, link, event, href, routerOptions);
+    }
+}

package/utils/live-element.d.ts

@@ -0,0 +1,8 @@
+type Bag = Record<string, unknown>;
+/**
+ * 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 declare function liveElement(props: Bag, ref: unknown, elementType: string, defaultClassName: string, omit?: readonly string[]): unknown;
+export {};