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

package/preview-trigger/index.jsx

@@ -0,0 +1,82 @@
+// Ported from React Aria Components (PreviewTrigger.tsx), Apache-2.0, © Adobe.
+// A PreviewTrigger displays a popover with a preview of a link's destination (or any rich content) on
+// hover, keyboard focus, or touch long press: `<PreviewTrigger><Link/><Popover>…</Popover></PreviewTrigger>`.
+// Unlike a tooltip, the popover may contain interactive content (Tab from the trigger moves into it).
+// Rivet:
+// - state: `createTooltipTriggerState({ delay: 600, closeDelay: 200 })` (shared warmup with tooltips),
+//   provided as `OverlayTriggerStateContext`; the Popover gets `PopoverContext` `{ trigger:
+//   "PreviewTrigger", triggerRef, ref, isNonModal: true, shouldSkipAnimation, id, onFocusWithin,
+//   onBlurWithin }` (RAC).
+// - the trigger props reach the child (a cdk Link / Button, or a custom element in `<Focusable>`) through
+//   FocusableProvider (RAC); `aria-haspopup="dialog"` is server-rendered, `aria-expanded` /
+//   `aria-controls` / `aria-describedby` are set on the trigger while the preview is open; the touch long
+//   press and the FocusScope restore listener are installed on the trigger at its first pointerenter /
+//   focus (delegated useLongPress / RA `useEvent(triggerRef, …)`).
+// - RA's effects (safe area, focus after long press, ARIA) run from a client effect in an own binding
+//   site (`span[data-rv-overlay-anchor]`) only while open — nothing at load.
+// Not yet supported: the long press accessibility description ("Long press to open preview").
+import { untrack } from "@rivetjs/reactivity";
+import { Show, clientEffect, ref as createRef } from "@rivetjs/runtime/dom";
+import { FocusableProvider } from "../focus/focusable.jsx";
+import { Provider } from "../slots/index.jsx";
+import { idSignal } from "../utils/id.js";
+import { OverlayTriggerStateContext, PopoverContext } from "../overlay/contexts.js";
+import { createTooltipTriggerState } from "../state/tooltip.js";
+import { attachPreviewTrigger, previewTriggerBlur, previewTriggerCheckClose, previewTriggerFocus, previewTriggerKeepOpen, previewTriggerKeyDown, previewTriggerPointerEnter, previewTriggerPointerLeave, } from "./behaviour.jsx";
+import { liveOptions } from "../utils/live.jsx";
+/** A PreviewTrigger displays a popover preview on hover, focus or long press of its trigger. */
+export function PreviewTrigger(props) {
+    const state = createTooltipTriggerState({
+        ...liveOptions(props, [], ["isOpen"]),
+        delay: props.delay ?? 600,
+        closeDelay: props.closeDelay ?? 200,
+    });
+    const triggerRef = createRef();
+    const popoverRef = createRef();
+    // RA mergeIds: a user `id` on the Popover replaces the generated one (the signal travels as `idRef`).
+    const popoverIdRef = idSignal();
+    const popoverId = untrack(popoverIdRef);
+    const isDisabled = props.isDisabled;
+    const options = {
+        isDisabled,
+        triggerRef: () => triggerRef(),
+        popoverRef: () => popoverRef(),
+        popoverId,
+    };
+    const children = props.children;
+    const popover = {
+        trigger: "PreviewTrigger",
+        triggerRef,
+        ref: popoverRef,
+        isNonModal: true,
+        shouldSkipAnimation: () => state.shouldSkipAnimation(),
+        id: popoverId,
+        idRef: popoverIdRef,
+        onFocusWithin: () => previewTriggerKeepOpen(state),
+        onBlurWithin: () => previewTriggerCheckClose(state, options),
+    };
+    return (<>
+      <Provider values={[
+            [OverlayTriggerStateContext, state],
+            [PopoverContext, popover],
+        ]}>
+        {() => (<FocusableProvider ref={triggerRef} aria-haspopup="dialog" aria-expanded={() => state.isOpen()} aria-controls={() => (state.isOpen() ? popoverIdRef() : undefined)} aria-describedby={() => (state.isOpen() ? popoverIdRef() : undefined)} onPointerEnter={(event) => previewTriggerPointerEnter(event, options, state)} onPointerLeave={(event) => previewTriggerPointerLeave(event, options, state)} onFocus={(event) => previewTriggerFocus(event, options, state)} onBlur={(event) => previewTriggerBlur(event, options, state)} onKeyDown={(event) => previewTriggerKeyDown(event, options, state)}>
+            {children}
+          </FocusableProvider>)}
+      </Provider>
+      <span data-rv-overlay-anchor="" style={{ display: "contents" }}>
+        <Show when={() => state.isOpen()}>{() => <PreviewEffects state={state} options={options}/>}</Show>
+      </span>
+    </>);
+}
+/** RA usePreviewTrigger's effects while open (safe area, focus after long press, the trigger's ARIA). */
+function PreviewEffects(props) {
+    const { state, options } = props;
+    clientEffect(() => {
+        // Wait for the popover (RA: effects after the popover rendered).
+        if (!options.popoverRef || !(typeof options.popoverRef === "function" ? options.popoverRef() : options.popoverRef))
+            return;
+        return attachPreviewTrigger(state, options);
+    });
+    return null;
+}

package/progress-bar/behaviour.d.ts

@@ -0,0 +1,77 @@
+import { type NumberFormatOptions } from "../number/NumberFormatter.js";
+import { type MaybeAccessor } from "../interactions/utils.js";
+export interface ProgressBarBaseProps {
+    /**
+     * The current value (controlled; a number or an accessor).
+     *
+     * @default 0
+     */
+    value?: MaybeAccessor<number | undefined>;
+    /**
+     * The smallest value allowed for the input.
+     *
+     * @default 0
+     */
+    minValue?: MaybeAccessor<number | undefined>;
+    /**
+     * The largest value allowed for the input.
+     *
+     * @default 100
+     */
+    maxValue?: MaybeAccessor<number | undefined>;
+    /** The content to display as the label (here: whether a visible label renders). */
+    label?: unknown;
+    /**
+     * The display format of the value label (live: a value or an accessor, read inside `aria-valuetext`).
+     *
+     * @default { style: 'percent' }
+     */
+    formatOptions?: MaybeAccessor<NumberFormatOptions | undefined>;
+    /** The content to display as the value's label (e.g. 1 of 4). */
+    valueLabel?: MaybeAccessor<string | undefined>;
+}
+export interface AriaProgressBarBaseProps extends ProgressBarBaseProps {
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+}
+export interface ProgressBarProps extends ProgressBarBaseProps {
+    /** Whether presentation is indeterminate when progress isn't known. */
+    isIndeterminate?: MaybeAccessor<boolean | undefined>;
+}
+export interface AriaProgressBarProps extends ProgressBarProps, AriaProgressBarBaseProps {
+}
+export interface ProgressBarAttrs {
+    id: string;
+    role: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+    /** Accessor: the clamped value, `undefined` while indeterminate. */
+    "aria-valuenow": () => number | undefined;
+    "aria-valuemin": () => number;
+    "aria-valuemax": () => number;
+    /** Accessor: `valueLabel` or the formatted value, `undefined` while indeterminate. */
+    "aria-valuetext": () => string | undefined;
+}
+export interface ProgressBarAria {
+    /** Props for the progress bar container element. */
+    progressBarProps: ProgressBarAttrs;
+    /** Props for the progress bar's visual label element (if any). */
+    labelProps: {
+        id?: string;
+    };
+}
+/**
+ * Provides the accessibility implementation for a progress bar component.
+ * Progress bars show either determinate or indeterminate progress of an operation
+ * over time.
+ */
+export declare function progressBarProps(props: AriaProgressBarProps, locale?: string): ProgressBarAria;
+/** RAC ProgressBar / Meter render value: the value as a percentage (0–100) of the range; 0 for an empty range. */
+export declare function percentageOf(value?: number, minValue?: number, maxValue?: number): number;
+/** `percentageOf` over `MaybeAccessor` props (tracked when they are accessors). */
+export declare function percentageOfProps(props: ProgressBarBaseProps): number;

package/progress-bar/behaviour.jsx

@@ -0,0 +1,75 @@
+// Ported from react-aria `useProgressBar` (packages/react-aria/src/progress/useProgressBar.ts), Apache-2.0, © Adobe.
+// Rivet:
+// - `progressBarProps(props, locale?)` (RA `useProgressBar`) returns `{ progressBarProps, labelProps }`; call it
+//   while rendering (it reads the locale context and creates ids, like the hook).
+// - value props are `MaybeAccessor`s (a number or `() => number`), and the value-dependent attributes of the bag
+//   (`aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-valuetext`) are accessors: read them inside bindings
+//   so a changing value updates the attributes only (accessor rule). `.tsx`: the accessors are resumable closures.
+// - The visual label (`label`) only decides whether a label id is created (RA `useLabel` with
+//   `labelElementType: 'span'`); RAC passes `createSlot`'s "a Label rendered" flag.
+// - `useNumberFormatter` → `NumberFormatter` (`@rivetjs/cdk/number`, cached Intl formatter per locale + options),
+//   created inside the `aria-valuetext` accessor so the accessor only captures plain data (locale, options).
+import { clamp } from "../utils/index.js";
+import { NumberFormatter } from "../number/NumberFormatter.js";
+import { useLocale } from "../i18n/index.js";
+import { labelAria } from "../label/behaviour.js";
+import { read } from "../interactions/utils.js";
+/** The resolved range of `props`: `[value (clamped), minValue, maxValue]`. */
+function rangeOf(props) {
+    const minValue = read(props.minValue) ?? 0;
+    const maxValue = read(props.maxValue) ?? 100;
+    return [clamp(read(props.value) ?? 0, minValue, maxValue), minValue, maxValue];
+}
+/**
+ * Provides the accessibility implementation for a progress bar component.
+ * Progress bars show either determinate or indeterminate progress of an operation
+ * over time.
+ */
+export function progressBarProps(props, locale = useLocale().locale) {
+    const { labelProps, fieldProps } = labelAria({
+        id: props.id,
+        label: props.label,
+        "aria-label": props["aria-label"],
+        "aria-labelledby": props["aria-labelledby"],
+        // Progress bar is not an HTML input element so it shouldn't be labeled by a <label> element.
+        labelElementType: "span",
+    });
+    const isIndeterminate = () => !!read(props.isIndeterminate);
+    const valueText = () => {
+        if (isIndeterminate())
+            return undefined;
+        const valueLabel = read(props.valueLabel);
+        if (valueLabel)
+            return valueLabel;
+        const [value, minValue, maxValue] = rangeOf(props);
+        const range = maxValue - minValue;
+        const percentage = range === 0 ? 0 : (value - minValue) / range;
+        const formatOptions = read(props.formatOptions) ?? { style: "percent" };
+        // Created per read (the Intl formatter is cached per locale + options): a captured NumberFormatter
+        // instance would not serialize into the resumable accessor.
+        return new NumberFormatter(locale, formatOptions).format(formatOptions.style === "percent" ? percentage : value);
+    };
+    const barProps = {
+        ...fieldProps,
+        role: "progressbar",
+        "aria-valuenow": () => (isIndeterminate() ? undefined : rangeOf(props)[0]),
+        "aria-valuemin": () => read(props.minValue) ?? 0,
+        "aria-valuemax": () => read(props.maxValue) ?? 100,
+        "aria-valuetext": valueText,
+    };
+    if (props["aria-describedby"])
+        barProps["aria-describedby"] = props["aria-describedby"];
+    if (props["aria-details"])
+        barProps["aria-details"] = props["aria-details"];
+    return { progressBarProps: barProps, labelProps: { id: labelProps.id } };
+}
+/** RAC ProgressBar / Meter render value: the value as a percentage (0–100) of the range; 0 for an empty range. */
+export function percentageOf(value = 0, minValue = 0, maxValue = 100) {
+    value = clamp(value, minValue, maxValue);
+    const range = maxValue - minValue;
+    return range === 0 ? 0 : ((value - minValue) / range) * 100;
+}
+/** `percentageOf` over `MaybeAccessor` props (tracked when they are accessors). */
+export function percentageOfProps(props) {
+    return percentageOf(read(props.value) ?? 0, read(props.minValue) ?? 0, read(props.maxValue) ?? 100);
+}

package/progress-bar/context.d.ts

@@ -0,0 +1,4 @@
+import { type ContextValue } from "../slots/index.jsx";
+import type { ProgressBarProps } from "./index.jsx";
+/** RAC `ProgressBarContext` (Button provides `{ id }` to its pending ProgressBar). */
+export declare const ProgressBarContext: import("@rivetjs/reactivity").Context<ContextValue<ProgressBarProps, HTMLDivElement>>;

package/progress-bar/context.js

@@ -0,0 +1,7 @@
+// RAC `ProgressBarContext` (react-aria-components ProgressBar.tsx), Apache-2.0, © Adobe. Its own module so a Button
+// (which provides `{ id }` to its pending ProgressBar) does not load the ProgressBar part, its behaviour and the
+// number formatter on pages without a ProgressBar.
+import { createContext } from "@rivetjs/reactivity";
+import { resumableContext } from "../slots/index.jsx";
+/** RAC `ProgressBarContext` (Button provides `{ id }` to its pending ProgressBar). */
+export const ProgressBarContext = resumableContext(createContext(null, { id: "rv-progress-bar" }));

package/progress-bar/index.d.ts

@@ -0,0 +1,38 @@
+import { type DOMRenderProps } from "../utils/render.js";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type RefValue, type ClassNameOrFunction, type RenderProps, type SlotProps } from "../slots/index.jsx";
+import { ProgressBarContext } from "./context.js";
+import { type AriaProgressBarProps } from "./behaviour.jsx";
+export { progressBarProps, percentageOf, type AriaProgressBarProps, type ProgressBarAria } from "./behaviour.jsx";
+export interface ProgressBarRenderProps {
+    /** The value as a percentage between the minimum and maximum (undefined while indeterminate). */
+    percentage: () => number | undefined;
+    /**
+     * A formatted version of the value.
+     *
+     * @selector [aria-valuetext]
+     */
+    valueText: () => string | undefined;
+    /**
+     * Whether the progress bar is indeterminate.
+     *
+     * @selector :not([aria-valuenow])
+     */
+    isIndeterminate: () => boolean;
+}
+export interface ProgressBarProps extends Omit<AriaProgressBarProps, "label">, RenderProps<ProgressBarRenderProps>, DOMRenderProps<"div", ProgressBarRenderProps>, SlotProps, Omit<GlobalDOMAttributes<HTMLDivElement>, "style"> {
+    ref?: RefValue<HTMLDivElement>;
+    /**
+     * The CSS class for the element. A function may be provided to compute the class based on component state.
+     *
+     * @default 'rv-ProgressBar'
+     */
+    class?: ClassNameOrFunction<ProgressBarRenderProps>;
+}
+/** RAC `ProgressBarContext`: `./context.ts` (Button imports it from there). */
+export { ProgressBarContext };
+/**
+ * Progress bars show either determinate or indeterminate progress of an operation
+ * over time.
+ */
+export declare function ProgressBar(props: ProgressBarProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/progress-bar/index.jsx

@@ -0,0 +1,90 @@
+// Ported from react-aria-components `ProgressBar` (packages/react-aria-components/src/ProgressBar.tsx), Apache-2.0, © Adobe.
+// Progress bars show either determinate or indeterminate progress of an operation over time.
+// Rivet:
+// - render props are accessors (`{({ percentage, valueText }) => <div style={{ width: percentage() + "%" }} />}`);
+//   `class` / `style` may be functions of them (RAC `className` → `class`).
+// - the label: `<Label>` inside gets `{ id, elementType: "span" }` from `LabelContext`; `aria-labelledby` points
+//   at it while it is attached (`createSlot`: server render assumes it is, when no `aria-label` / `aria-labelledby`).
+// - `value` / `minValue` / `maxValue` / `valueLabel` / `isIndeterminate` accept accessors (`value={() => progress()}`):
+//   the aria attributes and render props update in their bindings (the component runs once).
+// `render` (RAC DOMRenderProps): given, the attributes object (reactive entries are accessors) goes to `render(attrs, renderProps)` instead of the default element.
+import { untrack } from "@rivetjs/reactivity";
+import { hasLive, liveOptions, liveView } from "../utils/live.jsx";
+import { Provider } from "@rivetjs/runtime/dom";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { contextProps, createSlot, renderPropsOf, } from "../slots/index.jsx";
+import { LabelContext } from "../label/index.jsx";
+import { read } from "../interactions/utils.js";
+import { ProgressBarContext } from "./context.js";
+import { percentageOfProps, progressBarProps } from "./behaviour.jsx";
+export { progressBarProps, percentageOf } from "./behaviour.jsx";
+const OWNED = ["style", "render"];
+/** RAC `ProgressBarContext`: `./context.ts` (Button imports it from there). */
+export { ProgressBarContext };
+/**
+ * Progress bars show either determinate or indeterminate progress of an operation
+ * over time.
+ */
+export function ProgressBar(props) {
+    // Live props (P5): the value props become accessors (the bag reads them with `read` in bindings), class / style /
+    // children from a live view; the rest of the body is read once (untracked).
+    return untrack(() => progressBar(props));
+}
+const LIVE_KEYS = ["value", "minValue", "maxValue", "valueLabel", "isIndeterminate", "formatOptions"];
+function progressBar(props) {
+    const [ctxMerged, ref] = contextProps(props, props.ref, ProgressBarContext);
+    const merged = hasLive(ctxMerged) ? liveOptions(ctxMerged, LIVE_KEYS) : ctxMerged;
+    const indeterminate = merged.isIndeterminate;
+    const isIndeterminate = () => !!read(indeterminate);
+    const initialLabel = !merged["aria-label"] && !merged["aria-labelledby"];
+    const [labelRef, hasLabel] = createSlot(initialLabel);
+    // `children` left out: the bag's accessors (`aria-valuetext`, a render prop) must not capture them (resumed pages).
+    const { progressBarProps: barProps, labelProps } = progressBarProps({ ...merged, children: undefined, label: initialLabel });
+    const labelledBy = barProps["aria-labelledby"];
+    // Calculate the width of the progress bar as a percentage
+    // A narrow view of the range keys (not `merged`: the render props' `percentage` would capture the children too).
+    const range = liveView(merged, ["value", "minValue", "maxValue"]);
+    const percentage = () => (isIndeterminate() ? undefined : percentageOfProps(range));
+    const valueText = barProps["aria-valuetext"];
+    const values = { percentage, valueText, isIndeterminate };
+    const rp = renderPropsOf(merged, { defaultClassName: "rv-ProgressBar", values });
+    const dom = globalDOMProps(merged, OWNED);
+    const slot = merged.slot || undefined;
+    const { id, role } = barProps;
+    const ariaLabel = barProps["aria-label"];
+    const describedBy = barProps["aria-describedby"];
+    const details = barProps["aria-details"];
+    const valueNow = barProps["aria-valuenow"];
+    const valueMin = barProps["aria-valuemin"];
+    const valueMax = barProps["aria-valuemax"];
+    const labelValue = { id: labelProps.id, ref: labelRef, elementType: "span" };
+    if (merged.render) {
+        const attrs = {
+            ...dom,
+            ref: ref,
+            id,
+            role,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            slot,
+            "aria-label": ariaLabel,
+            "aria-labelledby": () => (initialLabel ? (hasLabel() ? labelledBy : undefined) : labelledBy),
+            "aria-describedby": describedBy,
+            "aria-details": details,
+            "aria-valuenow": valueNow,
+            "aria-valuemin": valueMin,
+            "aria-valuemax": valueMax,
+            "aria-valuetext": valueText,
+            children: () => (<Provider token={LabelContext} value={labelValue}>
+          {rp.children()}
+        </Provider>),
+        };
+        return merged.render(attrs, values);
+    }
+    return (<div {...dom} ref={ref} id={id} role={role} class={rp.class()} style={rp.style()} slot={slot} aria-label={ariaLabel} aria-labelledby={initialLabel ? (hasLabel() ? labelledBy : undefined) : labelledBy} aria-describedby={describedBy} aria-details={details} aria-valuenow={valueNow()} aria-valuemin={valueMin()} aria-valuemax={valueMax()} aria-valuetext={valueText()}>
+      <Provider token={LabelContext} value={labelValue}>
+        {rp.children()}
+      </Provider>
+    </div>);
+}

package/radio-group/behaviour.d.ts

@@ -0,0 +1,11 @@
+import { setSelectedValue, type RadioGroupState } from "../state/radio-group.js";
+/** Native validation of the group (RA useRadio `useFormValidation` on every radio). */
+export declare function syncRadioValidity(state: RadioGroupState, input: HTMLInputElement): void;
+/** `change` on a radio (`value` = the radio value). Read-only: restore the selected radio. */
+export declare function radioChange(state: RadioGroupState, value: string, event: Event): void;
+export declare function radioFocus(state: RadioGroupState, value: string, event: Event): void;
+/** RA useRadioGroup `onBlur` (focus-within): forget the last focused radio when focus leaves the group. */
+export declare function radioGroupFocusOut(state: RadioGroupState, event: FocusEvent): void;
+export declare function radioInvalid(state: RadioGroupState, event: Event): void;
+/** Programmatic selection (RA `state.setSelectedValue`). */
+export { setSelectedValue };

package/radio-group/behaviour.js

@@ -0,0 +1,85 @@
+// Ported from react-aria `useRadioGroup` + `useRadio` (packages/react-aria/src/radio/useRadioGroup.ts,
+// src/radio/useRadio.ts), Apache-2.0, © Adobe.
+// Rivet: native radios sharing a name give arrow-key navigation (wrap, skip disabled, select on arrow),
+// the single tab stop and form submission without JS; these handlers keep the state, read-only and
+// validation in step.
+import { untrack } from "@rivetjs/reactivity";
+import { DEFAULT_VALIDATION_RESULT, clearServerErrors, commitValidation, realtimeValidation, resetValidation, updateValidation, } from "../state/form-validation.js";
+import { nativeValidity, onFormReset, validationInvalid } from "../form/behaviour.js";
+import { isRadioGroupDisabled, isRadioGroupReadOnly, setLastFocusedValue, setSelectedValue } from "../state/radio-group.js";
+const radios = (input) => {
+    const group = input.closest('[role="radiogroup"]');
+    return group ? [...group.querySelectorAll('input[type="radio"]')] : [input];
+};
+/** Native validation of the group (RA useRadio `useFormValidation` on every radio). */
+export function syncRadioValidity(state, input) {
+    const { validation } = state;
+    onFormReset(state, input, () => {
+        if (!state.fixed)
+            state.selectedValue.set(state.defaultSelectedValue);
+        resetValidation(validation);
+    });
+    if (validation.behavior !== "native")
+        return;
+    const realtime = untrack(() => realtimeValidation(validation));
+    const message = realtime.isInvalid ? realtime.validationErrors.join(" ") || "Invalid value." : "";
+    const inputs = radios(input);
+    for (const el of inputs) {
+        if (el.disabled)
+            continue;
+        el.setCustomValidity(message);
+        if (!el.hasAttribute("title"))
+            el.title = "";
+    }
+    if (!realtime.isInvalid) {
+        const invalid = inputs.filter((el) => !el.disabled && !el.validity.valid).map(nativeValidity);
+        updateValidation(validation, invalid.length ? invalid[0] : DEFAULT_VALIDATION_RESULT);
+    }
+}
+/** `change` on a radio (`value` = the radio value). Read-only: restore the selected radio. */
+export function radioChange(state, value, event) {
+    const input = event.currentTarget;
+    event.stopPropagation();
+    if (isRadioGroupReadOnly(state) || isRadioGroupDisabled(state)) {
+        const selected = untrack(state.selectedValue);
+        for (const el of radios(input))
+            el.checked = el.value === selected;
+        return;
+    }
+    if (!input.checked)
+        return;
+    clearServerErrors(state.validation);
+    // RA setSelectedValue commits; sync the custom validity first (RA layout effect order).
+    if (untrack(state.selectedValue) !== value) {
+        if (!state.fixed)
+            state.selectedValue.set(value);
+        state.onChange?.(value);
+        // Controlled (plain / accessor value): the radios show the prop, not the click (React restores a controlled
+        // input) — re-sync after the caller's update has flushed.
+        if (state.fixed)
+            queueMicrotask(() => restoreRadios(state, input));
+    }
+    syncRadioValidity(state, input);
+    commitValidation(state.validation);
+}
+function restoreRadios(state, input) {
+    const selected = untrack(state.selectedValue);
+    for (const el of radios(input))
+        el.checked = el.value === selected;
+}
+export function radioFocus(state, value, event) {
+    setLastFocusedValue(state, value);
+    syncRadioValidity(state, event.currentTarget);
+}
+/** RA useRadioGroup `onBlur` (focus-within): forget the last focused radio when focus leaves the group. */
+export function radioGroupFocusOut(state, event) {
+    const group = event.currentTarget;
+    if (!group.contains(event.relatedTarget))
+        setLastFocusedValue(state, null);
+}
+export function radioInvalid(state, event) {
+    syncRadioValidity(state, event.currentTarget);
+    validationInvalid(state.validation, event);
+}
+/** Programmatic selection (RA `state.setSelectedValue`). */
+export { setSelectedValue };

package/radio-group/index.d.ts

@@ -0,0 +1,82 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Content, JSX, Slot } from "@rivetjs/runtime/jsx-runtime";
+import { type MaybeAccessor, type ValidationBehavior, type ValidationFunction, type ValidationResult } from "../state/form-validation.js";
+import { type GlobalDOMAttributes } from "@rivetjs/cdk/dom-props";
+import { type RadioGroupPartsProps } from "./parts.jsx";
+export type { RadioGroupState } from "../state/radio-group.js";
+export { Radio, RadioButton, RadioContext, RadioField, RadioFieldContext, RadioGroupContext, RadioGroupStateContext, radioProps, type AriaRadioProps, type RadioAria, type RadioButtonProps, type RadioButtonRenderProps, type RadioFieldProps, type RadioFieldRenderProps, type RadioGroupData, type RadioGroupPartsProps, type RadioGroupRenderProps, type RadioProps, type RadioRenderProps, } from "./parts.jsx";
+/** One radio (RAC `<Radio>` props): global DOM events / attributes go on its `<label>`, focus / key events (RA FocusableProps) on its input. */
+export interface RadioItem extends GlobalDOMAttributes<HTMLLabelElement> {
+    readonly value: string;
+    readonly label?: string;
+    readonly isDisabled?: boolean;
+    /** Help text of this radio (linked with aria-describedby). */
+    readonly description?: string;
+    /** Radio input id (default generated). */
+    readonly id?: string;
+    readonly onFocus?: (event: FocusEvent) => void;
+    readonly onBlur?: (event: FocusEvent) => void;
+    readonly onFocusChange?: (isFocused: boolean) => void;
+    readonly onKeyDown?: (event: KeyboardEvent) => void;
+    readonly onKeyUp?: (event: KeyboardEvent) => void;
+    /** @deprecated use `isDisabled` */ readonly disabled?: boolean;
+}
+/** Props of the data-driven preset (`items`). */
+export interface RadioGroupItemsProps extends GlobalDOMAttributes<HTMLDivElement> {
+    /** Visible group label (a `<span>`, referenced by aria-labelledby). */
+    label?: Content;
+    items: readonly RadioItem[];
+    /** Selected value (controlled): a two-way Signal, or a plain value (`value={v()}` stays live); or `defaultValue`. */
+    value?: Signal<string | null> | string | null;
+    defaultValue?: string | null;
+    onChange?: (value: string) => void;
+    /** Form field name (default: a generated id). */
+    name?: string;
+    form?: string;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    isRequired?: boolean;
+    isInvalid?: MaybeAccessor<boolean | undefined>;
+    validate?: ValidationFunction<string | null>;
+    /** @default "native" (or the enclosing `<Form>`'s) */
+    validationBehavior?: ValidationBehavior;
+    description?: Content;
+    errorMessage?: Content | ((validation: ValidationResult) => Content);
+    /** @default "vertical" */
+    orientation?: "vertical" | "horizontal";
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+    /** Focus entered the group (RA FocusEvents on the group: focus-within). */
+    onFocus?: (event: FocusEvent) => void;
+    /** Focus left the group. */
+    onBlur?: (event: FocusEvent) => void;
+    onFocusChange?: (isFocusWithin: boolean) => void;
+    /** @default "rv-RadioGroup" */
+    class?: string;
+    /** Radio (label) class, default `rv-Radio`. */
+    itemClass?: string;
+    inputClass?: string;
+    labelClass?: string;
+    descriptionClass?: string;
+    errorClass?: string;
+    /** Radio content (default: the item label). */
+    children?: Slot<[item: () => RadioItem]>;
+    /** @deprecated use `isRequired` */ required?: boolean;
+    /** @deprecated use `isDisabled` */ disabled?: boolean;
+    /** @deprecated use `aria-describedby` */ describedBy?: string;
+}
+/**
+ * A radio group allows a user to select a single item from a list of mutually exclusive options. With `items`: the data-driven preset
+ * (below); without: the RAC compound form (`<RadioField>` / `<RadioButton>` / `<Radio>` children, `./parts.tsx`).
+ */
+export declare function RadioGroup(props: RadioGroupPartsProps & {
+    items?: undefined;
+}): JSX.Element;
+export declare function RadioGroup(props: RadioGroupItemsProps): JSX.Element;
+/** `RadioGroup` props: the RAC compound props (`./parts.tsx`, no `items`) or the data-driven preset's (`RadioGroupItemsProps`). */
+export type RadioGroupProps = (RadioGroupPartsProps & {
+    items?: undefined;
+}) | RadioGroupItemsProps;