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

package/focus/focusable.jsx

@@ -0,0 +1,93 @@
+// Ported from react-aria useFocusable / Focusable / FocusableProvider / FocusableContext
+// (packages/react-aria/src/interactions/useFocusable.tsx), Apache-2.0, © Adobe.
+// Makes an element focusable and capable of auto focus; `FocusableContext` passes DOM props (e.g. a
+// TooltipTrigger's `aria-describedby` + focus handlers) to the nearest focusable child.
+// Rivet:
+// - `useFocusable(props, ref)` → `focusableProps(props, ref?)` returning RA's `focusableProps` bag
+//   (naming convention); handlers are resumable (focusProps / keyboardProps bags).
+// - autoFocus: a `clientEffect` focuses the ref'd element once (`focusSafely`), only when `autoFocus`.
+// - `FocusableContext` is registered for resume (id `rv-focusable`); its `ref` is a Rivet ref that the
+//   consumer's ref is synced to (RA `useSyncRef`) through `mergeRefValues`.
+// - Deviation: `<Focusable>` cannot clone its child (compiled templates): the child is a render
+//   function receiving the merged props, which it spreads on its element and whose `ref` it passes
+//   (`{(p) => <span {...p} ref={p.ref} role="button">…</span>}`: a spread never sets `ref`). Dev checks (child focusable / interactive
+//   role) run in a dev-only client effect.
+import { createContext, untrack, useContext } from "@rivetjs/reactivity";
+import { Provider as ContextProvider, clientEffect, ref as createRef } from "@rivetjs/runtime/dom";
+import { renderSlot } from "@rivetjs/runtime/slot";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { focusProps } from "../interactions/focus.jsx";
+import { keyboardProps } from "../interactions/keyboard.jsx";
+import { mergeProps } from "../interactions/merge-props.jsx";
+import { isFocusable } from "../interactions/utils.js";
+import { mergeRefValues } from "../slots/index.jsx";
+import { focusSafely } from "./index.js";
+/** DOM props for the nearest focusable child (RA `FocusableContext`, exported for collections). */
+export const FocusableContext = resumableContext(createContext(null, { id: "rv-focusable" }));
+/** Provides DOM props to the nearest focusable child (RA `FocusableProvider`). */
+export function FocusableProvider(props) {
+    const { children, ref, ...otherProps } = props;
+    const value = { ...otherProps, ref: ref ?? createRef() };
+    return (<ContextProvider token={FocusableContext} value={value}>
+      {renderSlot(children)}
+    </ContextProvider>);
+}
+/**
+ * Used to make an element focusable and capable of auto focus (RA `useFocusable(props, domRef).focusableProps`).
+ * Put `ref` (when given) on the element: autoFocus and the context's ref sync go through it.
+ */
+export function focusableProps(props, ref) {
+    const focus = focusProps(props);
+    const keyboard = keyboardProps(props);
+    const interactions = mergeProps(focus.focusProps, keyboard.keyboardProps);
+    const context = useContext(FocusableContext) || {};
+    const { ref: contextRef, ...domProps } = context;
+    const interactionProps = props.isDisabled ? {} : domProps;
+    const elementRef = mergeRefValues(ref, contextRef);
+    if (props.autoFocus && elementRef) {
+        const target = elementRef;
+        let done = false;
+        clientEffect(() => {
+            const el = typeof target === "function" ? target() : target.current;
+            if (!done && el)
+                untrack(() => focusSafely(el));
+            done = true;
+        });
+    }
+    // Always set a tabIndex so that Safari allows focusing native buttons and inputs.
+    let tabIndex = props.excludeFromTabOrder ? -1 : 0;
+    if (props.isDisabled)
+        tabIndex = undefined;
+    const out = mergeProps({ ...interactions, tabIndex }, interactionProps);
+    if (elementRef)
+        out.ref = elementRef;
+    return out;
+}
+const isDev = () => globalThis.process?.env?.NODE_ENV === "development";
+const INTERACTIVE_ROLES = /^(application|button|checkbox|combobox|gridcell|link|menuitem|menuitemcheckbox|menuitemradio|option|radio|searchbox|separator|slider|spinbutton|switch|tab|tabpanel|textbox|treeitem|img|meter|progressbar)$/;
+/** Makes its child focusable (RA `<Focusable>`); see the header for the render-function child. */
+export function Focusable(props) {
+    const { children, ref, ...options } = props;
+    const element = ref ?? createRef();
+    const merged = focusableProps(options, element);
+    if (isDev()) {
+        const isDisabled = options.isDisabled;
+        clientEffect(() => {
+            const el = typeof element === "function" ? element() : element.current;
+            if (!el)
+                return console.error("<Focusable> child must forward its ref to a DOM element.");
+            untrack(() => {
+                if (!isDisabled && !isFocusable(el, { skipVisibilityCheck: true }))
+                    return console.warn("<Focusable> child must be focusable. Please ensure the tabIndex prop is passed through.");
+                if (!/^(button|input|select|textarea|a|area|summary|img|svg)$/.test(el.localName)) {
+                    const role = el.getAttribute("role");
+                    if (!role)
+                        console.warn("<Focusable> child must have an interactive ARIA role.");
+                    else if (!INTERACTIVE_ROLES.test(role))
+                        console.warn(`<Focusable> child must have an interactive ARIA role. Got "${role}".`);
+                }
+            });
+        });
+    }
+    return renderSlot(children, merged);
+}

package/focus/index.d.ts

@@ -0,0 +1,74 @@
+import { type FocusableElement } from "../interactions/utils.js";
+/**
+ * Rivet: the mount effect of a server-rendered element (auto focus of a Dialog / FocusScope / `autoFocus`)
+ * runs on a resumed page when its chunk wakes (idle / visible), possibly after the user moved focus — React
+ * runs it at hydration, before any interaction. True when focus already left the body: auto focus then
+ * leaves it where the user put it.
+ */
+export declare function focusMovedByUser(doc: Document): boolean;
+/** Focus the first tabbable element inside `scope` (or `scope` itself when focusable); returns it. */
+export declare function focusFirst(scope: Element): HTMLElement | null;
+/** Focus the last tabbable element inside `scope`; returns it. */
+export declare function focusLast(scope: Element): HTMLElement | null;
+/**
+ * Keydown handler body that keeps Tab / Shift+Tab inside `scope` (wraps at the ends). Wire it on the
+ * scope element: `onKeyDown={(e) => containFocus(e.currentTarget, e)}`. Returns true when it moved focus.
+ */
+export declare function containFocus(scope: Element, event: KeyboardEvent): boolean;
+/**
+ * Remember the focused element now; the returned function focuses it again (if still connected and
+ * focus is not already elsewhere outside `within`). Use around custom overlays: save on open, call on close.
+ */
+export declare function saveFocus(within?: Element | null): () => void;
+/**
+ * Roving tabindex: make `item` the only tabbable item among `items` (tabindex 0, others -1) and focus
+ * it. Server markup renders the same tabindex values from state (`tabIndex={focused === key ? 0 : -1}`).
+ */
+export declare function roveFocus(items: Iterable<Element>, item: HTMLElement, options?: FocusOptions): void;
+/**
+ * Make everything outside `element` inert (siblings of it and of each ancestor up to `<body>`); the
+ * returned function restores the previous `inert` values. For custom modal surfaces (the overlay
+ * components use `ariaHideOutside`).
+ */
+export declare function inertOutside(element: Element): () => void;
+export interface FocusManagerOptions {
+    /** Element to start from (default: the focused element). */
+    from?: Element;
+    /** Only tabbable elements (default: all focusable). */
+    tabbable?: boolean;
+    /** Wrap around at the ends. */
+    wrap?: boolean;
+    /** Filter: whether an element may receive focus. */
+    accept?: (node: Element) => boolean;
+}
+export interface FocusManager {
+    /** Focus the next focusable / tabbable element in the scope. */
+    focusNext(opts?: FocusManagerOptions): FocusableElement | null;
+    /** Focus the previous focusable / tabbable element in the scope. */
+    focusPrevious(opts?: FocusManagerOptions): FocusableElement | null;
+    /** Focus the first focusable / tabbable element in the scope. */
+    focusFirst(opts?: FocusManagerOptions): FocusableElement | null;
+    /** Focus the last focusable / tabbable element in the scope. */
+    focusLast(opts?: FocusManagerOptions): FocusableElement | null;
+}
+/**
+ * Focus `element` without scrolling; when a screen reader's virtual cursor drives the interaction,
+ * wait for running CSS transitions first (VoiceOver on iOS scrolls to transitioning elements).
+ */
+export declare function focusSafely(element: FocusableElement): void;
+/** Whether `element` is inside one of the `scope` nodes. */
+export declare function isElementInScope(element: Element | null | undefined, scope: Element[] | null | undefined): boolean;
+/**
+ * A TreeWalker over the focusable (or tabbable) elements of `root` — radio groups collapse to their
+ * tab stop, `from`'s subtree is skipped, `scope` limits the nodes, `accept` filters.
+ */
+export declare function getFocusableTreeWalker(root: Element, opts?: FocusManagerOptions, scope?: Element[]): TreeWalker;
+type RootRef = (() => Element | null | undefined) | {
+    current: Element | null;
+};
+/**
+ * A FocusManager moving focus within `ref`'s element (react-aria `createFocusManager`). `ref`: a
+ * `ref()` object, an element accessor or `{ current }`. Browser only (call it in handlers).
+ */
+export declare function createFocusManager(ref: RootRef, defaultOptions?: FocusManagerOptions): FocusManager;
+export {};

package/focus/index.js

@@ -0,0 +1,274 @@
+// Focus management: containment (Tab trap), restore, roving tabindex, inert outside, for overlays
+// (the div overlay layer; `<FocusScope>` for components), composite widgets and custom roots.
+import { tabbables } from "../a11y/index.js";
+import { getActiveElement, getOwnerDocument, isFocusable as isFocusableElement, isTabbable as isTabbableElement, nodeContains, focusWithoutScrolling, runAfterTransition, } from "../interactions/utils.js";
+import { getInteractionModality } from "../interactions/focus-visible.jsx";
+import { cssEscape } from "../utils/dom.js";
+/**
+ * Rivet: the mount effect of a server-rendered element (auto focus of a Dialog / FocusScope / `autoFocus`)
+ * runs on a resumed page when its chunk wakes (idle / visible), possibly after the user moved focus — React
+ * runs it at hydration, before any interaction. True when focus already left the body: auto focus then
+ * leaves it where the user put it.
+ */
+export function focusMovedByUser(doc) {
+    const active = getActiveElement(doc);
+    return !!active && active !== doc.body && active !== doc.documentElement;
+}
+/** Focus the first tabbable element inside `scope` (or `scope` itself when focusable); returns it. */
+export function focusFirst(scope) {
+    const target = tabbables(scope)[0] ?? null;
+    target?.focus();
+    return target;
+}
+/** Focus the last tabbable element inside `scope`; returns it. */
+export function focusLast(scope) {
+    const list = tabbables(scope);
+    const target = list[list.length - 1] ?? null;
+    target?.focus();
+    return target;
+}
+/**
+ * Keydown handler body that keeps Tab / Shift+Tab inside `scope` (wraps at the ends). Wire it on the
+ * scope element: `onKeyDown={(e) => containFocus(e.currentTarget, e)}`. Returns true when it moved focus.
+ */
+export function containFocus(scope, event) {
+    if (event.key !== "Tab" || event.altKey || event.ctrlKey || event.metaKey)
+        return false;
+    const list = tabbables(scope);
+    if (!list.length) {
+        event.preventDefault();
+        return true;
+    }
+    // The element the key was pressed on, not `activeElement`: on a resumed page the first Tab runs
+    // this after the chunk loaded, when the browser has already moved focus (from the middle item to
+    // the last one, say) — comparing that new focus with the ends would wrap one step too early.
+    const first = list[0], last = list[list.length - 1], target = event.target instanceof Element ? event.target : null, active = target && target !== scope ? target : scope.ownerDocument.activeElement;
+    const outside = !active || !scope.contains(active);
+    if (event.shiftKey && (active === first || outside)) {
+        event.preventDefault();
+        last.focus();
+        return true;
+    }
+    if (!event.shiftKey && (active === last || outside)) {
+        event.preventDefault();
+        first.focus();
+        return true;
+    }
+    return false;
+}
+/**
+ * Remember the focused element now; the returned function focuses it again (if still connected and
+ * focus is not already elsewhere outside `within`). Use around custom overlays: save on open, call on close.
+ */
+export function saveFocus(within) {
+    const previous = typeof document === "undefined" ? null : document.activeElement;
+    return () => {
+        const active = document.activeElement;
+        const lost = !active || active === document.body || (within ? within.contains(active) : true);
+        if (previous?.isConnected && lost)
+            previous.focus({ preventScroll: true });
+    };
+}
+/**
+ * Roving tabindex: make `item` the only tabbable item among `items` (tabindex 0, others -1) and focus
+ * it. Server markup renders the same tabindex values from state (`tabIndex={focused === key ? 0 : -1}`).
+ */
+export function roveFocus(items, item, options) {
+    for (const other of items)
+        if (other !== item)
+            other.setAttribute("tabindex", "-1");
+    item.setAttribute("tabindex", "0");
+    item.focus(options);
+}
+/**
+ * Make everything outside `element` inert (siblings of it and of each ancestor up to `<body>`); the
+ * returned function restores the previous `inert` values. For custom modal surfaces (the overlay
+ * components use `ariaHideOutside`).
+ */
+export function inertOutside(element) {
+    const changed = [];
+    for (let node = element; node && node !== document.body; node = node.parentElement) {
+        const parent = node.parentElement;
+        if (!parent)
+            break;
+        for (const sibling of parent.children)
+            if (sibling !== node && !sibling.hasAttribute("inert") && sibling.localName !== "script") {
+                sibling.setAttribute("inert", "");
+                changed.push(sibling);
+            }
+    }
+    return () => {
+        for (const el of changed)
+            el.removeAttribute("inert");
+    };
+}
+/**
+ * Focus `element` without scrolling; when a screen reader's virtual cursor drives the interaction,
+ * wait for running CSS transitions first (VoiceOver on iOS scrolls to transitioning elements).
+ */
+export function focusSafely(element) {
+    if (!element.isConnected)
+        return;
+    const doc = getOwnerDocument(element);
+    if (getInteractionModality() === "virtual") {
+        const last = getActiveElement(doc);
+        runAfterTransition(() => {
+            const active = getActiveElement(doc);
+            // Focus did not move (or was lost to the body) meanwhile.
+            if ((active === last || active === doc.body) && element.isConnected)
+                focusWithoutScrolling(element);
+        });
+    }
+    else
+        focusWithoutScrolling(element);
+}
+function getRadiosInGroup(element) {
+    if (!element.form)
+        return [...getOwnerDocument(element).querySelectorAll(`input[type="radio"][name="${cssEscape(element.name)}"]`)].filter((radio) => !radio.form);
+    const list = element.form.elements.namedItem(element.name);
+    if (list instanceof RadioNodeList)
+        return [...list].filter((el) => el instanceof HTMLInputElement);
+    if (list instanceof HTMLInputElement)
+        return [list];
+    return [];
+}
+function isTabbableRadio(element) {
+    if (element.checked)
+        return true;
+    const radios = getRadiosInGroup(element);
+    return radios.length > 0 && !radios.some((radio) => radio.checked);
+}
+/** Whether `element` is inside one of the `scope` nodes. */
+export function isElementInScope(element, scope) {
+    if (!element || !scope)
+        return false;
+    return scope.some((node) => nodeContains(node, element));
+}
+/**
+ * A TreeWalker over the focusable (or tabbable) elements of `root` — radio groups collapse to their
+ * tab stop, `from`'s subtree is skipped, `scope` limits the nodes, `accept` filters.
+ */
+export function getFocusableTreeWalker(root, opts, scope) {
+    const filter = opts?.tabbable ? isTabbableElement : isFocusableElement;
+    const rootElement = root?.nodeType === Node.ELEMENT_NODE ? root : null;
+    const doc = getOwnerDocument(rootElement);
+    const walker = doc.createTreeWalker(root || doc, NodeFilter.SHOW_ELEMENT, {
+        acceptNode(node) {
+            // Skip nodes inside the starting node.
+            if (nodeContains(opts?.from, node))
+                return NodeFilter.FILTER_REJECT;
+            const element = node;
+            if (opts?.tabbable && element.tagName === "INPUT" && element.getAttribute("type") === "radio") {
+                if (!isTabbableRadio(element))
+                    return NodeFilter.FILTER_REJECT;
+                // Same group as the current node, none checked: skip.
+                const current = walker.currentNode;
+                if (current.tagName === "INPUT" && current.type === "radio" && current.name === element.name)
+                    return NodeFilter.FILTER_REJECT;
+            }
+            if (filter(element) && (!scope || isElementInScope(element, scope)) && (!opts?.accept || opts.accept(element)))
+                return NodeFilter.FILTER_ACCEPT;
+            return NodeFilter.FILTER_SKIP;
+        },
+    });
+    if (opts?.from)
+        walker.currentNode = opts.from;
+    return walker;
+}
+function lastNode(walker) {
+    let next;
+    let last;
+    do {
+        last = walker.lastChild();
+        if (last)
+            next = last;
+    } while (last);
+    return next;
+}
+function focusElement(element, scroll = false) {
+    if (element == null)
+        return;
+    try {
+        if (scroll)
+            element.focus();
+        else
+            focusSafely(element);
+    }
+    catch {
+        // ignore
+    }
+}
+const rootOf = (ref) => (typeof ref === "function" ? ref() : ref.current);
+/**
+ * A FocusManager moving focus within `ref`'s element (react-aria `createFocusManager`). `ref`: a
+ * `ref()` object, an element accessor or `{ current }`. Browser only (call it in handlers).
+ */
+export function createFocusManager(ref, defaultOptions = {}) {
+    return {
+        focusNext(opts = {}) {
+            const root = rootOf(ref);
+            if (!root)
+                return null;
+            const { from, tabbable = defaultOptions.tabbable, wrap = defaultOptions.wrap, accept = defaultOptions.accept } = opts;
+            const node = from || getActiveElement(getOwnerDocument(root));
+            const walker = getFocusableTreeWalker(root, { tabbable, accept });
+            if (nodeContains(root, node))
+                walker.currentNode = node;
+            let next = walker.nextNode();
+            if (!next && wrap) {
+                walker.currentNode = root;
+                next = walker.nextNode();
+            }
+            if (next)
+                focusElement(next, true);
+            return next;
+        },
+        focusPrevious(opts = defaultOptions) {
+            const root = rootOf(ref);
+            if (!root)
+                return null;
+            const { from, tabbable = defaultOptions.tabbable, wrap = defaultOptions.wrap, accept = defaultOptions.accept } = opts;
+            const node = from || getActiveElement(getOwnerDocument(root));
+            const walker = getFocusableTreeWalker(root, { tabbable, accept });
+            if (nodeContains(root, node))
+                walker.currentNode = node;
+            else {
+                const next = lastNode(walker);
+                if (next)
+                    focusElement(next, true);
+                return next ?? null;
+            }
+            let previous = walker.previousNode();
+            if (!previous && wrap) {
+                walker.currentNode = root;
+                const last = lastNode(walker);
+                if (!last)
+                    return null;
+                previous = last;
+            }
+            if (previous)
+                focusElement(previous, true);
+            return previous ?? null;
+        },
+        focusFirst(opts = defaultOptions) {
+            const root = rootOf(ref);
+            if (!root)
+                return null;
+            const { tabbable = defaultOptions.tabbable, accept = defaultOptions.accept } = opts;
+            const next = getFocusableTreeWalker(root, { tabbable, accept }).nextNode();
+            if (next)
+                focusElement(next, true);
+            return next;
+        },
+        focusLast(opts = defaultOptions) {
+            const root = rootOf(ref);
+            if (!root)
+                return null;
+            const { tabbable = defaultOptions.tabbable, accept = defaultOptions.accept } = opts;
+            const next = lastNode(getFocusableTreeWalker(root, { tabbable, accept }));
+            if (next)
+                focusElement(next, true);
+            return next ?? null;
+        },
+    };
+}

package/form/behaviour.d.ts

@@ -0,0 +1,29 @@
+import { type FormValidationState, type ValidationResult } from "../state/form-validation.js";
+export type ValidatableElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+/**
+ * `data-rv-error` attribute value (render it on the native input in `native` mode): the realtime
+ * error text, so `<Form>` can apply it as custom validity before a cold submit. Reads the state.
+ */
+export declare function validityError(state: FormValidationState): string | undefined;
+/** Snapshot of the element's native validity. */
+export declare function nativeValidity(input: ValidatableElement): ValidationResult;
+/**
+ * The layout effect of `useFormValidation`: native mode sets the realtime error as custom validity
+ * (prevents submit) and, when valid, records the native validity for the next commit.
+ */
+export declare function syncValidity(state: FormValidationState, input: ValidatableElement | null | undefined): void;
+/** `invalid` event on the native input (fires on submit / checkValidity; captured, it does not bubble). */
+export declare function validationInvalid(state: FormValidationState, event: Event, focus?: () => void): void;
+/** `change` on the native input: commit (RA `onChange` listener). */
+export declare function validationChange(state: FormValidationState, input: ValidatableElement | null): void;
+/** RA order: server errors cleared → (render) layout effect syncs the custom validity → effect commits. */
+export declare function commit(state: FormValidationState, input: ValidatableElement | null | undefined): void;
+/** Run `fn` when the input's form resets (once per state). */
+export declare function onFormReset(owner: object, input: ValidatableElement | HTMLElement | null | undefined, fn: () => void): void;
+/**
+ * `<Form>` submit (and any form's submit): apply `data-rv-error` of every field as custom validity
+ * (fields never interacted with have not synced it yet); when that makes the form invalid, cancel and
+ * report (fires `invalid` → fields commit and the first one focuses).
+ */
+export declare function applyPendingValidity(form: HTMLFormElement): boolean;
+export declare function formSubmit(event: SubmitEvent): void;

package/form/behaviour.js

@@ -0,0 +1,145 @@
+// Ported from react-aria `useFormValidation` + `useFormReset` (packages/react-aria/src/form/useFormValidation.ts,
+// src/utils/useFormReset.ts), Apache-2.0, © Adobe.
+// Rivet: no layout effect runs before interaction, so the native custom validity is synced from the
+// field's handlers (`syncValidity` at input / change / focus / invalid) and, for fields never touched,
+// by `<Form>`'s submit handler from the `data-rv-error` attribute the field renders (`formSubmit`).
+// Deviation: no `form.reset` override (`isIgnoredReset`: detects React's automatic form reset after
+// server actions; Rivet never resets forms programmatically), so every reset clears the validation.
+import { untrack } from "@rivetjs/reactivity";
+import { setInteractionModality } from "../interactions/focus-visible.jsx";
+import { clearServerErrors, commitValidation, displayValidation, realtimeValidation, resetValidation, updateValidation, } from "../state/form-validation.js";
+const ERROR_ATTR = "data-rv-error";
+/**
+ * `data-rv-error` attribute value (render it on the native input in `native` mode): the realtime
+ * error text, so `<Form>` can apply it as custom validity before a cold submit. Reads the state.
+ */
+export function validityError(state) {
+    if (state.behavior !== "native")
+        return undefined;
+    const realtime = realtimeValidation(state);
+    return realtime.isInvalid ? realtime.validationErrors.join(" ") || "Invalid value." : undefined;
+}
+/** Snapshot of the element's native validity. */
+export function nativeValidity(input) {
+    const v = input.validity;
+    return {
+        isInvalid: !v.valid,
+        validationDetails: {
+            badInput: v.badInput,
+            customError: v.customError,
+            patternMismatch: v.patternMismatch,
+            rangeOverflow: v.rangeOverflow,
+            rangeUnderflow: v.rangeUnderflow,
+            stepMismatch: v.stepMismatch,
+            tooLong: v.tooLong,
+            tooShort: v.tooShort,
+            typeMismatch: v.typeMismatch,
+            valueMissing: v.valueMissing,
+            valid: v.valid,
+        },
+        validationErrors: input.validationMessage ? [input.validationMessage] : [],
+    };
+}
+/**
+ * The layout effect of `useFormValidation`: native mode sets the realtime error as custom validity
+ * (prevents submit) and, when valid, records the native validity for the next commit.
+ */
+export function syncValidity(state, input) {
+    if (state.behavior !== "native" || !input || !("setCustomValidity" in input) || input.disabled)
+        return;
+    const realtime = untrack(() => realtimeValidation(state));
+    input.setCustomValidity(realtime.isInvalid ? realtime.validationErrors.join(" ") || "Invalid value." : "");
+    // Prevent the default tooltip for the validation message (Firefox).
+    if (!input.hasAttribute("title"))
+        input.title = "";
+    if (!realtime.isInvalid)
+        updateValidation(state, nativeValidity(input));
+    attachReset(state, input);
+}
+function firstInvalid(form) {
+    for (let i = 0; i < form.elements.length; i++) {
+        const element = form.elements[i];
+        if (element.validity?.valid === false)
+            return element;
+    }
+    return null;
+}
+/** `invalid` event on the native input (fires on submit / checkValidity; captured, it does not bubble). */
+export function validationInvalid(state, event, focus) {
+    const input = event.target;
+    // Only commit when not already displaying an error: keeps server errors the user did not fix.
+    if (!untrack(() => displayValidation(state)).isInvalid)
+        commit(state, input);
+    // Focus the first invalid input of the form unless the event was already handled.
+    const form = input.form;
+    if (!event.defaultPrevented && form && firstInvalid(form) === input) {
+        if (focus)
+            focus();
+        else
+            input.focus();
+        // Always show focus ring.
+        setInteractionModality("keyboard");
+    }
+    // Prevent the browser's error bubble.
+    event.preventDefault();
+}
+/** `change` on the native input: commit (RA `onChange` listener). */
+export function validationChange(state, input) {
+    commit(state, input);
+}
+/** RA order: server errors cleared → (render) layout effect syncs the custom validity → effect commits. */
+export function commit(state, input) {
+    clearServerErrors(state);
+    syncValidity(state, input);
+    commitValidation(state);
+}
+// Form reset (RA `useFormReset` + reset listener): attached on the first handler that sees the input.
+const resetFns = new WeakMap();
+const attached = new WeakSet();
+/** Run `fn` when the input's form resets (once per state). */
+export function onFormReset(owner, input, fn) {
+    const form = input?.form;
+    if (!form || attached.has(owner))
+        return;
+    attached.add(owner);
+    let fns = resetFns.get(form);
+    if (!fns) {
+        resetFns.set(form, (fns = new Set()));
+        // RA useFormReset: a reset cancelled (in the capture phase) resets nothing.
+        form.addEventListener("reset", (event) => {
+            if (event.defaultPrevented)
+                return;
+            for (const f of fns)
+                f();
+        });
+    }
+    fns.add(fn);
+}
+function attachReset(state, input) {
+    onFormReset(state, input, () => resetValidation(state));
+}
+/**
+ * `<Form>` submit (and any form's submit): apply `data-rv-error` of every field as custom validity
+ * (fields never interacted with have not synced it yet); when that makes the form invalid, cancel and
+ * report (fires `invalid` → fields commit and the first one focuses).
+ */
+export function applyPendingValidity(form) {
+    let changed = false;
+    for (const element of form.querySelectorAll(`[${ERROR_ATTR}]`)) {
+        const message = element.getAttribute(ERROR_ATTR) ?? "";
+        if (element.validationMessage !== message && !element.disabled) {
+            element.setCustomValidity(message);
+            changed = true;
+        }
+    }
+    return changed;
+}
+export function formSubmit(event) {
+    const form = event.currentTarget;
+    if (form.noValidate)
+        return;
+    if (applyPendingValidity(form) && !form.checkValidity()) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+    }
+}

package/form/field-error.d.ts

@@ -0,0 +1,38 @@
+import { type MaybeAccessor, type ValidationResult } from "../state/form-validation.js";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type RefValue, type ClassNameOrFunction, type RenderProps } from "../slots/index.jsx";
+import { type DOMRenderProps } from "../utils/render.js";
+/** RAC `FieldErrorContext`: the validation of the enclosing field (`null` outside a field). */
+export declare const FieldErrorContext: import("@rivetjs/reactivity").Context<MaybeAccessor<ValidationResult | null>>;
+/** RAC `FieldErrorRenderProps` (= `ValidationResult`), as accessors. */
+export interface FieldErrorRenderProps {
+    /** Whether the input value is invalid. */
+    isInvalid: () => boolean;
+    /** The current error messages for the input if it is invalid, otherwise an empty array. */
+    validationErrors: () => string[];
+    /** The native validation details for the input. */
+    validationDetails: () => ValidationState;
+}
+type ValidationState = ValidationResult["validationDetails"];
+export interface FieldErrorProps extends RenderProps<FieldErrorRenderProps>, DOMRenderProps<"span", undefined>, Omit<GlobalDOMAttributes<HTMLElement>, "style"> {
+    /** The element's unique identifier. */
+    id?: string;
+    /**
+     * The CSS class for the element. A function may be provided to compute the class based on component state.
+     *
+     * @default 'rv-FieldError'
+     */
+    class?: ClassNameOrFunction<FieldErrorRenderProps>;
+    /**
+     * The HTML element type to render. Set to `'div'` when using block-level children (e.g. `<ul>`).
+     *
+     * @default 'span'
+     */
+    elementType?: string;
+    ref?: RefValue<HTMLElement>;
+}
+/**
+ * A FieldError displays validation errors for a form field.
+ */
+export declare function FieldError(props: FieldErrorProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement | null;
+export {};