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

package/i18n/list-formatter.js

@@ -0,0 +1,11 @@
+// Ported from react-spectrum (react-aria src/i18n/useListFormatter.tsx), Apache-2.0, © Adobe.
+//
+// Localized list formatting ("A, B, and C") for SelectValue / ComboBoxValue.
+// Rivet: `useListFormatter(options)` → `listFormatter(locale, options)`; the locale is an explicit
+// string (resolved at render) and formatters are cached per locale + options (`intl-cache.ts`;
+// upstream memoizes per component).
+import { cachedIntl } from "./intl-cache.js";
+/** Cached `Intl.ListFormat` for `locale` + `options` (react-aria `useListFormatter`). */
+export function listFormatter(locale, options) {
+    return cachedIntl(Intl.ListFormat, locale, options);
+}

package/input/index.d.ts

@@ -0,0 +1,51 @@
+import { type DOMRenderProps } from "../utils/render.js";
+import { type ClassNameOrFunction, type ContextValue, type AccessorProps, type HTMLProps, type RefValue, type SlotProps, type StyleOrFunction } from "../slots/index.jsx";
+import type { HoverEvents } from "../utils/types.js";
+export interface InputRenderProps {
+    /**
+     * Whether the input is currently hovered with a mouse.
+     *
+     * @selector [data-hovered]
+     */
+    isHovered: () => boolean;
+    /**
+     * Whether the input is focused, either via a mouse or keyboard.
+     *
+     * @selector [data-focused]
+     */
+    isFocused: () => boolean;
+    /**
+     * Whether the input is keyboard focused.
+     *
+     * @selector [data-focus-visible]
+     */
+    isFocusVisible: () => boolean;
+    /**
+     * Whether the input is disabled.
+     *
+     * @selector [data-disabled]
+     */
+    isDisabled: () => boolean;
+    /**
+     * Whether the input is invalid.
+     *
+     * @selector [data-invalid]
+     */
+    isInvalid: () => boolean;
+}
+export interface InputProps extends AccessorProps<HTMLProps<"input">, "autoFocus">, HoverEvents, SlotProps, DOMRenderProps<"input", InputRenderProps> {
+    /**
+     * The CSS class of the element. A function may be provided to compute the class based on component state.
+     *
+     * @default "rv-Input"
+     */
+    class?: ClassNameOrFunction<InputRenderProps>;
+    /** The inline style of the element. A function may be provided to compute the style based on component state. */
+    style?: StyleOrFunction<InputRenderProps>;
+    /** Temporary text that occupies the text input when it is empty. */
+    placeholder?: string;
+    ref?: RefValue<HTMLInputElement>;
+}
+export declare const InputContext: import("@rivetjs/reactivity").Context<ContextValue<InputProps, HTMLInputElement>>;
+/** An input allows a user to input text. */
+export declare function Input(props: InputProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement | null;

package/input/index.jsx

@@ -0,0 +1,95 @@
+// Ported from react-aria-components Input (packages/react-aria-components/src/Input.tsx), Apache-2.0, © Adobe.
+// A native `<input>` with hover / focus / focus-visible state (`data-hovered`, `data-focused`,
+// `data-focus-visible`, `data-disabled`, `data-invalid`); fields provide `InputContext`.
+// Rivet: props merged with `InputContext` (`contextProps`); render props are accessors
+// (`isHovered()`), `class` / `style` functions run inside bindings; state attributes are written by
+// bindings over the hover / focus-ring signals, so nothing runs before the first interaction.
+// `render` (RAC DOMRenderProps): given, the attributes go to `render(attrs, InputRenderProps)` instead of the default element. Deviations: not a hideable collection component.
+// - `autoFocus`: React focuses an `autoFocus` input when it mounts (also one created later, e.g. inside an opened popover); the native
+//   attribute only acts at page load, so a `clientEffect` focuses the element once (`focusSafely`). Only with `autoFocus` (the ref is
+//   then merged with an own `ref()`); the default path is unchanged.
+import { createContext, untrack } from "@rivetjs/reactivity";
+import { hasLive, liveAt, liveOmit, readOnce } from "../utils/live.jsx";
+import { liveRenderProps, slottedContext } from "../slots/index.jsx";
+import { mergeIds } from "../utils/id.js";
+import { clientEffect, ref as createRef } from "@rivetjs/runtime/dom";
+import { focusSafely } from "../focus/index.js";
+import { useFocusRing } from "../focus/focus-ring.jsx";
+import { hoverProps } from "../interactions/hover.jsx";
+import { mergeInto } from "../interactions/merge-props.jsx";
+import { read } from "../interactions/utils.js";
+import {} from "../utils/render.js";
+import { resumableContext, contextProps, renderProps, mergeRefValues, } from "../slots/index.jsx";
+import { isHiddenPart } from "../collections/hidden.js";
+import { slotProbing } from "#server";
+export const InputContext = resumableContext(createContext({}, { id: "rv-input" }));
+/** An input allows a user to input text. */
+export function Input(props) {
+    // RAC createHideableComponent: nothing in the collection build pass (its context providers are absent).
+    if (slotProbing) {
+        // A field's server slot probe: an own `id` merges into the field's input id now (RA mergeIds), so the Label that
+        // renders before this Input writes `for` = this id, as the client render does (the real render merges too late).
+        const own = props.id;
+        const ctxId = slottedContext(InputContext, props.slot)?.id;
+        if (typeof own === "string" && own && typeof ctxId === "string" && ctxId)
+            mergeIds(ctxId, own);
+        return null;
+    }
+    if (isHiddenPart())
+        return null;
+    const [merged, contextRef] = contextProps(props, props.ref, InputContext);
+    let ref = contextRef;
+    if (read(merged.autoFocus)) {
+        const own = createRef();
+        ref = mergeRefValues(own, contextRef);
+        let done = false;
+        clientEffect(() => {
+            const el = own();
+            if (!done && el && untrack(() => el.ownerDocument.activeElement) !== el)
+                untrack(() => focusSafely(el));
+            done = true;
+        });
+    }
+    // Live props (P5): read-once keys untracked, the rest forwarded unread (`liveOmit`); class / style from a live view.
+    const live = hasLive(merged);
+    const { onHoverStart, onHoverEnd, onHoverChange, class: className, style, slot, render, } = readOnce(merged, ["onHoverStart", "onHoverEnd", "onHoverChange", "class", "style", "slot", "render"]);
+    const rest = liveOmit(merged, ["onHoverStart", "onHoverEnd", "onHoverChange", "class", "style", "slot", "render"]);
+    // Context values may be accessors (fields provide reactive `aria-invalid`, `disabled`, …): read in bindings.
+    const disabledValue = liveAt(rest, "disabled");
+    const invalidValue = liveAt(rest, "aria-invalid");
+    const disabled = () => !!read(disabledValue);
+    const isInvalid = () => {
+        const v = read(invalidValue);
+        return !!v && v !== "false";
+    };
+    const hover = hoverProps({ onHoverStart, onHoverEnd, onHoverChange, isDisabled: disabled }, rest);
+    const isHovered = hover.isHovered;
+    const { isFocused, isFocusVisible, focusProps } = useFocusRing({
+        isTextInput: true,
+        autoFocus: untrack(() => read(rest.autoFocus)),
+    });
+    const rp = renderProps({
+        class: className,
+        style,
+        values: { isHovered, isFocused, isFocusVisible, isDisabled: disabled, isInvalid },
+        defaultClassName: "rv-Input",
+    }, live ? liveRenderProps(merged, ["class", "style"]) : undefined);
+    // Accessor values are resolved by the element spread (ACCESSOR RULE).
+    // `rest` is this part's own (read no more below): the static path merges into it in place.
+    const domProps = mergeInto(rest, focusProps, hover.hoverProps);
+    const s = slot ?? undefined;
+    if (render)
+        return render({
+            ...domProps,
+            slot: s,
+            ref: ref,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "data-focused": () => isFocused() || undefined,
+            "data-disabled": () => disabled() || undefined,
+            "data-hovered": () => isHovered() || undefined,
+            "data-focus-visible": () => isFocusVisible() || undefined,
+            "data-invalid": () => isInvalid() || undefined,
+        }, { isHovered, isFocused, isFocusVisible, isDisabled: disabled, isInvalid });
+    return (<input {...domProps} slot={s} ref={ref} class={rp.class()} style={rp.style()} data-focused={isFocused() || undefined} data-disabled={disabled() || undefined} data-hovered={isHovered() || undefined} data-focus-visible={isFocusVisible() || undefined} data-invalid={isInvalid() || undefined}/>);
+}

package/interactions/controllable.d.ts

@@ -0,0 +1,42 @@
+import { type Signal } from "@rivetjs/reactivity";
+/** Controlled state of one value (serializable: signals + plain data + the caller's `onChange`). */
+export interface ControlledState<T, C = T> {
+    /**
+     * The shown value (read `state.value()` in bindings). Do not `.set` it: use `setControlledValue`. For an
+     * accessor `value` (`isAccessor`) it IS the caller's read-only accessor (typed `Signal` for compatibility; no
+     * `set` / `update` — read it untracked with `untrack(state.value)`).
+     */
+    readonly value: Signal<T>;
+    /** Whether the caller controls the value (passed `value`, plain or Signal). */
+    readonly isControlled: boolean;
+    /** Whether the caller passed a Signal (two-way). */
+    readonly isSignal: boolean;
+    /** Whether the caller passed a plain function (read-only accessor: controlled, never written). */
+    readonly isAccessor: boolean;
+    /** The caller's change handler. */
+    readonly onChange: ((value: C, ...args: any[]) => void) | undefined;
+    /** @internal upstream `valueRef`: the latest value set in the current task (`has` false: none). */
+    readonly pending: {
+        has: boolean;
+        v: T | undefined;
+    };
+}
+/**
+ * @deprecated Two-argument form (two-way Signal or region signal, no `onChange`): kept until the
+ * `state/*` factories move to the three-argument form. Returns the signal itself.
+ */
+export declare function controllable<T>(value: Signal<T> | undefined, defaultValue: T): Signal<T>;
+/**
+ * react-stately `useControlledState`: `value` (plain, Signal or accessor `() => T`) controls, else an internal
+ * signal starting at `defaultValue`. Read `state.value()`; change with `setControlledValue(state, next)`.
+ * When `T` is itself a function type, wrap a plain value: `() => fn`.
+ */
+export declare function controllable<T, C = T>(value: T | Signal<T> | (() => T) | undefined, defaultValue: T, onChange: ((value: C, ...args: any[]) => void) | undefined): ControlledState<T, C>;
+/** The current value, including a value set earlier in the same task (upstream `valueRef.current`). */
+export declare function controlledValue<T>(state: ControlledState<T, any>): T;
+/**
+ * upstream `setValue`: `next` (or `next(previous)`) differing (`Object.is`) from the latest value updates
+ * an uncontrolled / Signal value and calls `onChange(next, ...args)`; a plain or accessor controlled value
+ * only calls `onChange`. Several calls in one task chain on each other's result.
+ */
+export declare function setControlledValue<T>(state: ControlledState<T, any>, next: T | ((previous: T) => T), ...args: any[]): void;

package/interactions/controllable.js

@@ -0,0 +1,67 @@
+// Ported from react-stately `useControlledState` (packages/react-stately/src/utils/useControlledState.ts),
+// Apache-2.0, © Adobe.
+// Controlled / uncontrolled component values with RAC prop names (`value` / `defaultValue` / `onChange`,
+// `isOpen` / `defaultOpen` / `onOpenChange`, …).
+// Rivet:
+// - `value` is a plain value OR a `Signal` (decision 2). A Signal is two-way: setting writes it (the
+//   caller's state IS the signal) and calls `onChange`. A plain value is controlled as upstream: setting
+//   only calls `onChange`; the shown value changes when the caller re-renders with a new `value` (a prop
+//   reading a signal re-creates the component).
+// - a plain function (no `.set`) is an accessor (accessor rule): controlled, read live (`state.value()` tracks
+//   it), never written — setting only calls `onChange`; the caller's state moves the value. Ambiguity: when `T`
+//   itself is a function type, pass it wrapped (`value={() => fn}`) or as a Signal.
+// - state = plain data (signals + JSON + the caller's `onChange`), so it serializes on resumed pages;
+//   setters are free functions (`setControlledValue`). The uncontrolled signal is region state
+//   (`_regionState`): a re-created region keeps it.
+// - upstream `valueRef` (the latest value set during the current render, so several setState calls in one
+//   event chain) = `pending`, reset after the current task (microtask) instead of after the next render.
+// - controlled ⇄ uncontrolled switches cannot happen (a changed prop re-creates the component), so the
+//   upstream switch warning has no trigger; instead DEV warns once for a plain controlled `value` without
+//   `onChange` (read-only, like React's `<input value>` warning).
+import { signal, _regionState } from "@rivetjs/reactivity";
+import { DEV, devWhere } from "#dev";
+const isSignal = (v) => typeof v === "function" && typeof v.set === "function";
+const isDev = () => globalThis.process?.env?.NODE_ENV === "development";
+export function controllable(value, defaultValue, onChange) {
+    // eslint-disable-next-line prefer-rest-params
+    if (arguments.length < 3)
+        return value ?? _regionState(() => signal(defaultValue));
+    const isControlled = value !== undefined;
+    const sig = isSignal(value);
+    const accessor = !sig && typeof value === "function";
+    if (DEV && isControlled && !sig && !onChange && isDev())
+        console.warn("[rivet:cdk] controllable: A component has a controlled value but no onChange handler; it is read-only. Pass a Signal or an onChange handler." +
+            devWhere());
+    return {
+        // Upstream: `useState(value || defaultValue)` — a falsy controlled value still shows (controlled wins).
+        value: sig || accessor ? value : isControlled ? signal(value) : _regionState(() => signal(defaultValue)),
+        isControlled,
+        isSignal: sig,
+        isAccessor: accessor,
+        onChange,
+        pending: { has: false, v: undefined },
+    };
+}
+/** The current value, including a value set earlier in the same task (upstream `valueRef.current`). */
+export function controlledValue(state) {
+    return state.pending.has ? state.pending.v : state.value();
+}
+/**
+ * upstream `setValue`: `next` (or `next(previous)`) differing (`Object.is`) from the latest value updates
+ * an uncontrolled / Signal value and calls `onChange(next, ...args)`; a plain or accessor controlled value
+ * only calls `onChange`. Several calls in one task chain on each other's result.
+ */
+export function setControlledValue(state, next, ...args) {
+    const previous = controlledValue(state);
+    const value = typeof next === "function" ? next(previous) : next;
+    if (Object.is(previous, value))
+        return;
+    const pending = state.pending;
+    if (!pending.has)
+        queueMicrotask(() => ((pending.has = false), (pending.v = undefined)));
+    pending.has = true;
+    pending.v = value;
+    if (!state.isControlled || state.isSignal)
+        state.value.set(value);
+    state.onChange?.(value, ...args);
+}

package/interactions/focus-visible.d.ts

@@ -0,0 +1,68 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type PointerType } from "./utils.js";
+export type Modality = "keyboard" | "pointer" | "virtual";
+type HandlerEvent = PointerEvent | MouseEvent | KeyboardEvent | FocusEvent | null;
+type Handler = (modality: Modality, e: HandlerEvent) => void;
+export type FocusVisibleHandler = (isFocusVisible: boolean) => void;
+export interface FocusVisibleProps {
+    /** Whether the element is a text input. */
+    isTextInput?: boolean;
+    /** Whether the element will be auto focused. */
+    autoFocus?: boolean;
+}
+export interface FocusVisibleResult {
+    /** Whether keyboard focus is visible globally (signal). */
+    isFocusVisible: () => boolean;
+}
+/** Subscribers to modality changes (browser-only functions). */
+export declare const changeHandlers: Set<Handler>;
+/** Install the global listeners for the element's window (idempotent). Browser only. */
+export declare function setupGlobalFocusEvents(element?: Element | null): void;
+/**
+ * Track focus visibility in another window (an iframe), given an element inside it; the default
+ * window is tracked on first use. Returns the function removing the listeners.
+ */
+export declare function addWindowFocusTracking(element?: HTMLElement | null): () => void;
+/**
+ * Called by focus handlers: installs tracking and, when the modality is still unknown (the page
+ * resumed and nothing tracked the event that moved focus), adopts the browser's `:focus-visible`
+ * verdict for the focused element.
+ */
+export declare function syncModalityFromFocus(target: Element | null): void;
+/** Whether keyboard focus is visible (modality is not pointer). */
+export declare function isFocusVisible(): boolean;
+export declare function getInteractionModality(): Modality | null;
+export declare function setInteractionModality(modality: Modality): void;
+/** @internal Tests: reset the modality (`null` = unknown) without notifying listeners. */
+export declare function _setInteractionModality(modality: Modality | null): void;
+/**
+ * Record the modality of a DOM event a resumed handler received: the global listeners install on
+ * first use, so they may have missed the very event that loaded the handler's chunk. Runs the same
+ * classification as the document listeners (modifier-only keys ignored, virtual clicks / pointers
+ * detected) and installs the listeners for later events. Collection / select / tabs handlers call it.
+ */
+export declare function noteModality(e: Event): void;
+/** @private The pointer type of the last interaction. */
+export declare function getPointerType(): PointerType;
+/** On text inputs, keyboard events other than Tab / Escape do not toggle focus visibility. */
+export declare function isKeyboardFocusEvent(isTextInput: boolean, modality: Modality, e: HandlerEvent): boolean;
+/**
+ * Subscribe `fn` to focus-visible changes (browser only, outside components: a handler or effect).
+ * Returns the unsubscribe function. The component-level form is `useFocusVisibleListener`.
+ */
+export declare function addFocusVisibleListener(fn: FocusVisibleHandler, opts?: {
+    isTextInput?: boolean;
+}): () => void;
+/**
+ * Listen for modality changes and report whether focus is visible. Deviation: no React `deps`; the
+ * listener is a client effect (resumed pages: installed when the runtime starts).
+ */
+export declare function watchFocusVisible(fn: FocusVisibleHandler, opts?: {
+    enabled?: boolean | (() => boolean);
+    isTextInput?: boolean;
+}): void;
+/** The current modality as a signal (`null` on the server and until the first interaction). */
+export declare function createInteractionModality(): Signal<Modality | null>;
+/** Focus-visible state for the page (signal), updated on modality changes. */
+export declare function createFocusVisible(props?: FocusVisibleProps): FocusVisibleResult;
+export {};

package/interactions/focus-visible.jsx

@@ -0,0 +1,291 @@
+// Global interaction modality tracking (keyboard / pointer / virtual) and focus-visible state.
+// Ported from @react-aria/interactions useFocusVisible (react-spectrum), Apache-2.0, © Adobe.
+//
+// Deviation (resumability, no import-time globals): the original installs its document listeners when
+// the module is imported. Here they install on first use — `addWindowFocusTracking()`, any hook's
+// handler, or the `useFocusVisible` / `useInteractionModality` client effect. Until then the modality
+// is unknown (`null`, focus visible like the original's initial state); a focus handler running before
+// installation infers it from the browser's own `:focus-visible` heuristic (`syncModalityFromFocus`).
+import { signal } from "@rivetjs/reactivity";
+import { clientEffect } from "@rivetjs/runtime/dom";
+import { focusGuard, getActiveElement, getEventTarget, getOwnerDocument, getOwnerWindow, isMac, isVirtualClick, linkState, nonTextInputTypes, } from "./utils.js";
+// Mutable module state lives in one object: resume-extracted symbols import module bindings read-only.
+const g = {
+    currentModality: null,
+    currentPointerType: "keyboard",
+    hasEventBeforeFocus: false,
+    hasBlurredWindowRecently: false,
+};
+/** Subscribers to modality changes (browser-only functions). */
+export const changeHandlers = new Set();
+const tracked = new Map();
+// Only Tab or Escape make focus visible on text inputs.
+const FOCUS_VISIBLE_INPUT_KEYS = { Tab: true, Escape: true };
+function triggerChangeHandlers(modality, e) {
+    for (const handler of changeHandlers)
+        handler(modality, e);
+}
+/** Unmodified key that could make keyboard focus visible (Control / Shift fire when returning to the tab). */
+function isValidKey(e) {
+    return !(e.metaKey || (!isMac() && e.altKey) || e.ctrlKey || e.key === "Control" || e.key === "Shift" || e.key === "Meta");
+}
+function handleKeyboardEvent(e) {
+    g.hasEventBeforeFocus = true;
+    if (!linkState.isOpening && isValidKey(e)) {
+        g.currentModality = "keyboard";
+        g.currentPointerType = "keyboard";
+        triggerChangeHandlers("keyboard", e);
+    }
+}
+function handlePointerEvent(e) {
+    g.currentModality = "pointer";
+    g.currentPointerType = "pointerType" in e ? e.pointerType : "mouse";
+    if (e.type === "mousedown" || e.type === "pointerdown") {
+        g.hasEventBeforeFocus = true;
+        triggerChangeHandlers("pointer", e);
+    }
+}
+function handleClickEvent(e) {
+    if (!linkState.isOpening && isVirtualClick(e)) {
+        g.hasEventBeforeFocus = true;
+        g.currentModality = "virtual";
+        g.currentPointerType = "virtual";
+    }
+}
+function handleFocusEvent(e) {
+    if (focusGuard.ignore)
+        return;
+    const target = getEventTarget(e);
+    const win = getOwnerWindow(target), doc = getOwnerDocument(target);
+    // Window focus (tab / app switch): restored element focus must not switch to virtual. Safari fires
+    // the window/element pair twice, so re-arm on every window focus.
+    if (target === win) {
+        g.hasBlurredWindowRecently = true;
+        return;
+    }
+    // Firefox: extra window/document focus events when first clicking into an iframe.
+    if (target === doc || !e.isTrusted)
+        return;
+    // Focus without a preceding key / pointer event: virtual (e.g. iOS form next/previous buttons).
+    if (!g.hasEventBeforeFocus && !g.hasBlurredWindowRecently) {
+        g.currentModality = "virtual";
+        g.currentPointerType = "virtual";
+        triggerChangeHandlers("virtual", e);
+    }
+    g.hasEventBeforeFocus = false;
+    g.hasBlurredWindowRecently = false;
+}
+function handleWindowBlur() {
+    if (focusGuard.ignore)
+        return;
+    // Tabbing out of the window: no focus event follows, so reset.
+    g.hasEventBeforeFocus = false;
+    g.hasBlurredWindowRecently = true;
+}
+function handleInvalidEvent(e) {
+    const doc = getOwnerDocument(getEventTarget(e));
+    const starting = getActiveElement(doc);
+    // A forms library moved focus to the first invalid field: keyboard modality.
+    queueMicrotask(() => {
+        if (getActiveElement(doc) !== starting)
+            setInteractionModality("keyboard");
+    });
+}
+/** Install the global listeners for the element's window (idempotent). Browser only. */
+export function setupGlobalFocusEvents(element) {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return;
+    const win = getOwnerWindow(element), doc = getOwnerDocument(element);
+    if (tracked.get(win))
+        return;
+    // A resumed page installs these on first use: the resume loader's last input modality covers the events before it.
+    if (g.currentModality === null)
+        adoptLoaderModality(win);
+    // Programmatic focus() must not switch the modality; other focus without a user event (screen
+    // reader) does. Patching HTMLElement.prototype.focus marks programmatic calls.
+    const focus = win.HTMLElement.prototype.focus;
+    Reflect.defineProperty(win.HTMLElement.prototype, "focus", {
+        configurable: true,
+        writable: true,
+        value: function (...args) {
+            g.hasEventBeforeFocus = true;
+            focus.apply(this, args);
+        },
+    });
+    doc.addEventListener("keydown", handleKeyboardEvent, true);
+    doc.addEventListener("keyup", handleKeyboardEvent, true);
+    doc.addEventListener("click", handleClickEvent, true);
+    doc.addEventListener("invalid", handleInvalidEvent, true);
+    // Window capture: before any document listener.
+    win.addEventListener("focus", handleFocusEvent, true);
+    win.addEventListener("blur", handleWindowBlur, false);
+    doc.addEventListener("pointerdown", handlePointerEvent, true);
+    doc.addEventListener("pointermove", handlePointerEvent, true);
+    doc.addEventListener("pointerup", handlePointerEvent, true);
+    win.addEventListener("beforeunload", () => tearDownWindowFocusTracking(element), { once: true });
+    tracked.set(win, { focus });
+}
+/**
+ * The resume loader's record of the last user input before any cdk code ran (`window.__rvIM`: "keyboard", a pointer
+ * type "mouse" / "pen" / "touch", or "virtual"; set by capture listeners in the loader, RESUME-PINS request). Absent
+ * (client render, older loader): the modality stays unknown and focus handlers fall back to `:focus-visible`.
+ */
+function adoptLoaderModality(win) {
+    const last = win.__rvIM;
+    if (last === "keyboard" || last === "virtual") {
+        g.currentModality = last;
+        g.currentPointerType = last;
+    }
+    else if (last === "mouse" || last === "pen" || last === "touch") {
+        g.currentModality = "pointer";
+        g.currentPointerType = last;
+    }
+}
+function tearDownWindowFocusTracking(element, loadListener) {
+    const win = getOwnerWindow(element), doc = getOwnerDocument(element);
+    if (loadListener)
+        doc.removeEventListener("DOMContentLoaded", loadListener);
+    const entry = tracked.get(win);
+    if (!entry)
+        return;
+    Reflect.defineProperty(win.HTMLElement.prototype, "focus", { configurable: true, writable: true, value: entry.focus });
+    doc.removeEventListener("keydown", handleKeyboardEvent, true);
+    doc.removeEventListener("keyup", handleKeyboardEvent, true);
+    doc.removeEventListener("click", handleClickEvent, true);
+    doc.removeEventListener("invalid", handleInvalidEvent, true);
+    win.removeEventListener("focus", handleFocusEvent, true);
+    win.removeEventListener("blur", handleWindowBlur, false);
+    doc.removeEventListener("pointerdown", handlePointerEvent, true);
+    doc.removeEventListener("pointermove", handlePointerEvent, true);
+    doc.removeEventListener("pointerup", handlePointerEvent, true);
+    tracked.delete(win);
+}
+/**
+ * Track focus visibility in another window (an iframe), given an element inside it; the default
+ * window is tracked on first use. Returns the function removing the listeners.
+ */
+export function addWindowFocusTracking(element) {
+    const doc = getOwnerDocument(element);
+    let loadListener;
+    if (doc.readyState !== "loading")
+        setupGlobalFocusEvents(element);
+    else
+        doc.addEventListener("DOMContentLoaded", (loadListener = () => setupGlobalFocusEvents(element)));
+    return () => tearDownWindowFocusTracking(element, loadListener);
+}
+/**
+ * Called by focus handlers: installs tracking and, when the modality is still unknown (the page
+ * resumed and nothing tracked the event that moved focus), adopts the browser's `:focus-visible`
+ * verdict for the focused element.
+ */
+export function syncModalityFromFocus(target) {
+    setupGlobalFocusEvents(target);
+    if (g.currentModality !== null || !target)
+        return;
+    let visible;
+    try {
+        visible = target.matches(":focus-visible");
+    }
+    catch {
+        return;
+    }
+    g.currentModality = visible ? "keyboard" : "pointer";
+    g.currentPointerType = visible ? "keyboard" : "mouse";
+}
+/** Whether keyboard focus is visible (modality is not pointer). */
+export function isFocusVisible() {
+    return g.currentModality !== "pointer";
+}
+export function getInteractionModality() {
+    return g.currentModality;
+}
+export function setInteractionModality(modality) {
+    g.currentModality = modality;
+    g.currentPointerType = modality === "pointer" ? "mouse" : modality;
+    triggerChangeHandlers(modality, null);
+}
+/** @internal Tests: reset the modality (`null` = unknown) without notifying listeners. */
+export function _setInteractionModality(modality) {
+    g.currentModality = modality;
+    g.currentPointerType = modality === "pointer" || modality === null ? "mouse" : modality;
+}
+/**
+ * Record the modality of a DOM event a resumed handler received: the global listeners install on
+ * first use, so they may have missed the very event that loaded the handler's chunk. Runs the same
+ * classification as the document listeners (modifier-only keys ignored, virtual clicks / pointers
+ * detected) and installs the listeners for later events. Collection / select / tabs handlers call it.
+ */
+export function noteModality(e) {
+    setupGlobalFocusEvents(getEventTarget(e) ?? undefined);
+    if (e.type === "keydown" || e.type === "keyup")
+        handleKeyboardEvent(e);
+    else if (e.type === "click")
+        handleClickEvent(e);
+    else if (e.type === "pointerdown" || e.type === "pointerup" || e.type === "pointermove" || e.type === "mousedown" || e.type === "mouseup")
+        handlePointerEvent(e);
+    else if (e.type.startsWith("touch")) {
+        g.currentModality = "pointer";
+        g.currentPointerType = "touch";
+    }
+}
+/** @private The pointer type of the last interaction. */
+export function getPointerType() {
+    return g.currentPointerType;
+}
+/** On text inputs, keyboard events other than Tab / Escape do not toggle focus visibility. */
+export function isKeyboardFocusEvent(isTextInput, modality, e) {
+    const target = e ? getEventTarget(e) : undefined;
+    const win = getOwnerWindow(target);
+    const active = getActiveElement(getOwnerDocument(target));
+    isTextInput =
+        isTextInput ||
+            (active instanceof win.HTMLInputElement && !nonTextInputTypes.has(active.type)) ||
+            active instanceof win.HTMLTextAreaElement ||
+            (active instanceof win.HTMLElement && active.isContentEditable);
+    return !(isTextInput && modality === "keyboard" && e instanceof win.KeyboardEvent && !FOCUS_VISIBLE_INPUT_KEYS[e.key]);
+}
+/**
+ * Subscribe `fn` to focus-visible changes (browser only, outside components: a handler or effect).
+ * Returns the unsubscribe function. The component-level form is `useFocusVisibleListener`.
+ */
+export function addFocusVisibleListener(fn, opts) {
+    setupGlobalFocusEvents();
+    const handler = (modality, e) => {
+        if (!isKeyboardFocusEvent(!!opts?.isTextInput, modality, e))
+            return;
+        fn(isFocusVisible());
+    };
+    changeHandlers.add(handler);
+    return () => changeHandlers.delete(handler);
+}
+/**
+ * Listen for modality changes and report whether focus is visible. Deviation: no React `deps`; the
+ * listener is a client effect (resumed pages: installed when the runtime starts).
+ */
+export function watchFocusVisible(fn, opts) {
+    clientEffect(() => {
+        const enabled = typeof opts?.enabled === "function" ? opts.enabled() : opts?.enabled;
+        if (enabled === false)
+            return;
+        return addFocusVisibleListener(fn, { isTextInput: opts?.isTextInput });
+    });
+}
+/** The current modality as a signal (`null` on the server and until the first interaction). */
+export function createInteractionModality() {
+    const modality = signal(null);
+    clientEffect(() => {
+        setupGlobalFocusEvents();
+        modality.set(g.currentModality);
+        const handler = () => modality.set(g.currentModality);
+        changeHandlers.add(handler);
+        return () => changeHandlers.delete(handler);
+    });
+    return modality;
+}
+/** Focus-visible state for the page (signal), updated on modality changes. */
+export function createFocusVisible(props = {}) {
+    const { isTextInput, autoFocus } = props;
+    const visible = signal(!!autoFocus || isFocusVisible());
+    clientEffect(() => addFocusVisibleListener((value) => visible.set(value), { isTextInput }));
+    return { isFocusVisible: visible };
+}