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

package/interactions/focus.d.ts

@@ -0,0 +1,58 @@
+import { type MaybeAccessor } from "./utils.js";
+export interface FocusEvents<E extends Event = FocusEvent> {
+    /** Called when the element receives focus. */
+    onFocus?: (e: E) => void;
+    /** Called when the element loses focus. */
+    onBlur?: (e: E) => void;
+    /** Called when the element's focus status changes. */
+    onFocusChange?: (isFocused: boolean) => void;
+}
+export interface FocusProps extends FocusEvents {
+    /** Disable the focus events (read at event time). */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+}
+export interface FocusResult {
+    /** Handlers to spread onto the target element. */
+    focusProps: Record<string, unknown>;
+}
+export interface FocusWithinProps {
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+    /** Called when the target or a descendant receives focus. */
+    onFocusWithin?: (e: FocusEvent) => void;
+    /** Called when the target and all descendants lose focus. */
+    onBlurWithin?: (e: FocusEvent) => void;
+    /** Called when the focus-within state changes. */
+    onFocusWithinChange?: (isFocusWithin: boolean) => void;
+}
+export interface FocusWithinResult {
+    focusWithinProps: Record<string, unknown>;
+}
+/** @internal blur handler of focusProps. */
+export declare function focusBlur(props: FocusProps, e: FocusEvent): boolean | undefined;
+/** @internal focus handler of focusProps. */
+export declare function focusFocus(props: FocusProps, e: FocusEvent): void;
+/** The transient blur listener of one focus handler (`off`: removes it). */
+export interface BlurSlot {
+    off?: () => void;
+}
+/**
+ * Bind `onBlur` as a native `blur` listener on the focused `el` until it fires (one per `slot`): the blur half of
+ * a delegated `focusin` handler (`blur` does not bubble; no listener per element before a focus).
+ */
+export declare function bindBlur(el: EventTarget, slot: BlurSlot, onBlur: (e: FocusEvent) => void): void;
+/** Focus events for the immediate target; focus events of children are ignored. */
+export declare function focusProps(props?: FocusProps): FocusResult;
+interface FocusWithin {
+    props: FocusWithinProps;
+    state: {
+        isFocusWithin: boolean;
+        globals: (() => void)[];
+    };
+}
+/** @internal focusout handler of focusWithinProps. */
+export declare function focusWithinBlur(within: FocusWithin, e: FocusEvent): void;
+/** @internal focusin handler of focusWithinProps. */
+export declare function focusWithinFocus(within: FocusWithin, e: FocusEvent): void;
+/** Focus events for the target and its descendants (focus-within). */
+export declare function focusWithinProps(props?: FocusWithinProps): FocusWithinResult;
+export {};

package/interactions/focus.jsx

@@ -0,0 +1,152 @@
+// focusProps (the target itself) and focusWithinProps (the target or a descendant), with the synthetic
+// blur for elements disabled while focused (Firefox fires no focusout then).
+// Ported from @react-aria/interactions useFocus / useFocusWithin (react-spectrum), Apache-2.0,
+// © Adobe; portions from React (react-interactions), MIT, © Meta.
+//
+// Rivet: React's onFocus / onBlur are focusin / focusout (delegated at the root); here useFocus binds the
+// native `focus` / `blur` (only when a callback is given), so handlers merged around its bag keep React Aria's
+// mergeProps chain order; useFocusWithin binds `focusin` / `focusout` (both delegated). Handlers are resumable
+// symbols. Rivet-internal focus state (useFocusRing, cdk data-* writers) uses the delegated `focusin` + a native
+// `blur` bound while focused (`bindBlur`): it carries no user callbacks and runs after every native focus handler
+// of the element, where React Aria's components merge it (last).
+import { getActiveElement, getEventTarget, getOwnerDocument, getOwnerWindow, nodeContains, read } from "./utils.js";
+/**
+ * React fires no blur for an element that becomes disabled while focused (Firefox fires no focusout
+ * either): watch the `disabled` attribute and dispatch blur + focusout ourselves.
+ */
+function watchDisabledBlur(e, onBlur) {
+    const target = getEventTarget(e);
+    if (!(target instanceof HTMLButtonElement ||
+        target instanceof HTMLInputElement ||
+        target instanceof HTMLTextAreaElement ||
+        target instanceof HTMLSelectElement))
+        return;
+    let focused = true;
+    let observer = null;
+    target.addEventListener("focusout", (event) => {
+        focused = false;
+        if (target.disabled)
+            onBlur(event);
+        observer?.disconnect();
+        observer = null;
+    }, { once: true });
+    observer = new MutationObserver(() => {
+        if (focused && target.disabled) {
+            observer?.disconnect();
+            const related = target === getActiveElement() ? null : getActiveElement();
+            target.dispatchEvent(new FocusEvent("blur", { relatedTarget: related }));
+            target.dispatchEvent(new FocusEvent("focusout", { bubbles: true, relatedTarget: related }));
+        }
+    });
+    observer.observe(target, { attributes: true, attributeFilter: ["disabled"] });
+}
+/** @internal blur handler of focusProps. */
+export function focusBlur(props, e) {
+    if (read(props.isDisabled))
+        return;
+    if (getEventTarget(e) === e.currentTarget) {
+        props.onBlur?.(e);
+        props.onFocusChange?.(false);
+        return true;
+    }
+}
+/** @internal focus handler of focusProps. */
+export function focusFocus(props, e) {
+    if (read(props.isDisabled))
+        return;
+    // A previous focus handler may already have moved focus elsewhere.
+    const target = getEventTarget(e);
+    const active = getActiveElement(getOwnerDocument(target));
+    if (target === e.currentTarget && target === active) {
+        props.onFocus?.(e);
+        props.onFocusChange?.(true);
+        watchDisabledBlur(e, (event) => focusBlur(props, event));
+    }
+}
+/**
+ * Bind `onBlur` as a native `blur` listener on the focused `el` until it fires (one per `slot`): the blur half of
+ * a delegated `focusin` handler (`blur` does not bubble; no listener per element before a focus).
+ */
+export function bindBlur(el, slot, onBlur) {
+    slot.off?.();
+    const listener = (e) => {
+        slot.off?.();
+        onBlur(e);
+    };
+    el.addEventListener("blur", listener);
+    slot.off = () => (el.removeEventListener("blur", listener), (slot.off = undefined));
+}
+/** Focus events for the immediate target; focus events of children are ignored. */
+export function focusProps(props = {}) {
+    // Conditional handlers as separate object literals: R2 wraps object-literal function values, not
+    // conditional expressions in them (queued compiler work).
+    // Native `focus` / `blur` (not the delegated `focusin`): the bag carries user callbacks, and a handler merged
+    // around it must run in React Aria's mergeProps chain order (`mergeProps(focusProps, { onFocus })`: the hook's
+    // `onFocus` / `onFocusChange` first). Listeners only when a callback is given.
+    const focusProps = {};
+    if (props.onFocus || props.onFocusChange || props.onBlur)
+        Object.assign(focusProps, { onFocus: (e) => focusFocus(props, e) });
+    if (props.onBlur || props.onFocusChange)
+        Object.assign(focusProps, { onBlur: (e) => focusBlur(props, e) });
+    return { focusProps };
+}
+/** @internal focusout handler of focusWithinProps. */
+export function focusWithinBlur(within, e) {
+    const { state, props } = within;
+    if (read(props.isDisabled))
+        return;
+    const currentTarget = e.currentTarget;
+    // Ignore events bubbling through portals.
+    if (!nodeContains(currentTarget, getEventTarget(e)))
+        return;
+    // Moving focus inside the element: no blur-within / focus-within pair.
+    if (state.isFocusWithin && !nodeContains(currentTarget, e.relatedTarget)) {
+        state.isFocusWithin = false;
+        for (const remove of state.globals.splice(0))
+            remove();
+        props.onBlurWithin?.(e);
+        props.onFocusWithinChange?.(false);
+    }
+}
+/** @internal focusin handler of focusWithinProps. */
+export function focusWithinFocus(within, e) {
+    const { state, props } = within;
+    if (read(props.isDisabled))
+        return;
+    const currentTarget = e.currentTarget;
+    if (!nodeContains(currentTarget, getEventTarget(e)))
+        return;
+    const target = getEventTarget(e);
+    const doc = getOwnerDocument(target);
+    if (!state.isFocusWithin && getActiveElement(doc) === target) {
+        props.onFocusWithin?.(e);
+        props.onFocusWithinChange?.(true);
+        state.isFocusWithin = true;
+        watchDisabledBlur(e, (event) => focusWithinBlur(within, withCurrentTarget(event, currentTarget)));
+        // Removed elements fire no blur: a focus outside the element ends focus-within.
+        const onFocus = (event) => {
+            const next = getEventTarget(event);
+            if (state.isFocusWithin && !nodeContains(currentTarget, next)) {
+                const blur = new (getOwnerWindow(doc).FocusEvent)("blur", { relatedTarget: next });
+                Object.defineProperty(blur, "target", { value: currentTarget });
+                focusWithinBlur(within, withCurrentTarget(blur, currentTarget));
+            }
+        };
+        doc.addEventListener("focus", onFocus, { capture: true });
+        state.globals.push(() => doc.removeEventListener("focus", onFocus, { capture: true }));
+    }
+}
+function withCurrentTarget(event, currentTarget) {
+    Object.defineProperty(event, "currentTarget", { value: currentTarget, configurable: true });
+    return event;
+}
+/** Focus events for the target and its descendants (focus-within). */
+export function focusWithinProps(props = {}) {
+    const within = { props, state: { isFocusWithin: false, globals: [] } };
+    return {
+        focusWithinProps: {
+            onFocusIn: (e) => focusWithinFocus(within, e),
+            onFocusOut: (e) => focusWithinBlur(within, e),
+        },
+    };
+}

package/interactions/hover.d.ts

@@ -0,0 +1,54 @@
+import { type MaybeAccessor } from "./utils.js";
+export interface HoverEvent {
+    type: "hoverstart" | "hoverend";
+    pointerType: "mouse" | "pen";
+    target: HTMLElement;
+}
+export interface HoverEvents {
+    onHoverStart?: (e: HoverEvent) => void;
+    onHoverEnd?: (e: HoverEvent) => void;
+    onHoverChange?: (isHovering: boolean) => void;
+}
+export interface HoverProps extends HoverEvents {
+    /** Disable hover events (read at event time). */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+}
+export interface HoverResult {
+    /** Handlers to spread on the target element (`onPointerOver`: delegated, the leave binds while hovered). */
+    hoverProps: Record<string, unknown>;
+    /** Hover state (signal accessor). */
+    isHovered: () => boolean;
+}
+/** Install the global touch listener once (browser only). */
+export declare function setupGlobalTouchEvents(): void;
+interface Hover {
+    props: HoverProps;
+    /** Native `onPointerEnter` / `onPointerLeave` bag (the leave is the bag's, no transient one). */
+    native?: boolean;
+    state: {
+        isHovered: boolean;
+        pointerType: string;
+        target: HTMLElement | null;
+        globals: (() => void)[];
+    };
+    hovered: {
+        set(value: boolean): unknown;
+    };
+}
+/**
+ * @internal pointerover handler of hoverProps (delegated): an enter of `currentTarget` when the pointer comes from
+ * outside it (React's pointerenter emulation).
+ */
+export declare function hoverPointerOver(hover: Hover, e: PointerEvent): void;
+/** @internal pointerenter handler (a native listener per element; prefer `hoverPointerOver`). */
+export declare function hoverPointerEnter(hover: Hover, e: PointerEvent): void;
+/** @internal pointerleave handler of a hover (bound on the hovered element while hovered). */
+export declare function hoverPointerLeave(hover: Hover, e: PointerEvent): void;
+/** End a hover now (the original's `isDisabled` effect: call when a disabled signal turns true). */
+export declare function endHover(hover: Hover): void;
+/**
+ * Pointer hover interactions for an element; ignores emulated mouse events on touch devices.
+ * Spread `hoverProps` on the target.
+ */
+export declare function hoverProps(props?: HoverProps, dom?: object | null): HoverResult;
+export {};

package/interactions/hover.jsx

@@ -0,0 +1,139 @@
+// hoverProps: pointer hover (mouse / pen) with emulated-mouse-after-touch suppression (iOS fires
+// pointerenter twice: touch, then mouse) and hover end when the hovered element is removed.
+// Ported from @react-aria/interactions useHover (react-spectrum), Apache-2.0, © Adobe; portions from
+// React (react-interactions), MIT, © Meta.
+//
+// Rivet: resumable handlers + `isHovered` signal. Deviation: the global touch listener (sets the
+// "ignore emulated mouse" flag for 500 ms after a touch pointerup) installs on the first handler call,
+// not at mount, so a page whose first-ever interaction is a touch is covered by the pointerType check
+// alone (touch enters never hover).
+// Delegated when nothing can observe the order (no hover callbacks, no pointer enter / leave handler merged before
+// the bag; else native `onPointerEnter` / `onPointerLeave`, React Aria's chain order) —
+// React's model: React emulates onPointerEnter / onPointerLeave from root pointerover / pointerout:
+// the hover starts from the runtime-delegated `pointerover` (`onPointerOver`, no listener per element; an
+// over whose `relatedTarget` is inside the element is a move within it, not an enter) and the hovered
+// element gets a transient native `pointerleave` listener until the hover ends (one at a time, not one per
+// instance). Edge: a `pointerover` stopped below the element (stopPropagation) starts no hover.
+import { signal } from "@rivetjs/reactivity";
+import { browserDocument, getEventTarget, getOwnerDocument, nodeContains, read } from "./utils.js";
+// Mutable module state in one object (resume-extracted symbols import module bindings read-only).
+const g = { globalIgnoreEmulatedMouseEvents: false, touchTracking: false };
+function setGlobalIgnoreEmulatedMouseEvents() {
+    g.globalIgnoreEmulatedMouseEvents = true;
+    // iOS fires the emulated mouse pointerenter right after pointerup; elsewhere do not ignore a much later hover.
+    setTimeout(() => (g.globalIgnoreEmulatedMouseEvents = false), 500);
+}
+function handleGlobalPointerEvent(e) {
+    if (e.pointerType === "touch")
+        setGlobalIgnoreEmulatedMouseEvents();
+}
+/** Install the global touch listener once (browser only). */
+export function setupGlobalTouchEvents() {
+    const doc = browserDocument();
+    if (g.touchTracking || !doc)
+        return;
+    g.touchTracking = true;
+    doc.addEventListener("pointerup", handleGlobalPointerEvent);
+}
+function triggerHoverStart(hover, event, pointerType) {
+    const { state, props } = hover;
+    state.pointerType = pointerType;
+    const currentTarget = event.currentTarget;
+    if (read(props.isDisabled) || pointerType === "touch" || state.isHovered || !nodeContains(currentTarget, getEventTarget(event)))
+        return;
+    state.isHovered = true;
+    state.target = currentTarget;
+    // A removed hovered element fires no pointerleave; the next pointerover elsewhere ends the hover.
+    const doc = getOwnerDocument(getEventTarget(event));
+    const onOver = (e) => {
+        if (state.isHovered && state.target && !nodeContains(state.target, getEventTarget(e)))
+            triggerHoverEnd(hover, e, e.pointerType);
+    };
+    doc.addEventListener("pointerover", onOver, { capture: true });
+    if (hover.native)
+        state.globals.push(() => doc.removeEventListener("pointerover", onOver, { capture: true }));
+    else {
+        // The leave of the hovered element (native, the target itself): bound while hovered only.
+        const onLeave = (e) => hoverPointerLeave(hover, e);
+        currentTarget.addEventListener("pointerleave", onLeave);
+        state.globals.push(() => (doc.removeEventListener("pointerover", onOver, { capture: true }), currentTarget.removeEventListener("pointerleave", onLeave)));
+    }
+    props.onHoverStart?.({ type: "hoverstart", target: currentTarget, pointerType: pointerType });
+    props.onHoverChange?.(true);
+    hover.hovered.set(true);
+}
+function triggerHoverEnd(hover, _event, pointerType) {
+    const { state, props } = hover;
+    const target = state.target;
+    state.pointerType = "";
+    state.target = null;
+    if (pointerType === "touch" || !state.isHovered || !target)
+        return;
+    state.isHovered = false;
+    for (const remove of state.globals.splice(0))
+        remove();
+    props.onHoverEnd?.({ type: "hoverend", target, pointerType: pointerType });
+    props.onHoverChange?.(false);
+    hover.hovered.set(false);
+}
+/**
+ * @internal pointerover handler of hoverProps (delegated): an enter of `currentTarget` when the pointer comes from
+ * outside it (React's pointerenter emulation).
+ */
+export function hoverPointerOver(hover, e) {
+    setupGlobalTouchEvents();
+    if (nodeContains(e.currentTarget, e.relatedTarget))
+        return; // a move within the element
+    if (g.globalIgnoreEmulatedMouseEvents && e.pointerType === "mouse")
+        return;
+    triggerHoverStart(hover, e, e.pointerType);
+}
+/** @internal pointerenter handler (a native listener per element; prefer `hoverPointerOver`). */
+export function hoverPointerEnter(hover, e) {
+    if (e.target === e.currentTarget)
+        hoverPointerOver(hover, e); // not a delegated dispatch of a descendant's enter
+}
+/** @internal pointerleave handler of a hover (bound on the hovered element while hovered). */
+export function hoverPointerLeave(hover, e) {
+    if (e.target !== e.currentTarget)
+        return;
+    if (!read(hover.props.isDisabled) && nodeContains(e.currentTarget, getEventTarget(e)))
+        triggerHoverEnd(hover, e, e.pointerType);
+}
+/** End a hover now (the original's `isDisabled` effect: call when a disabled signal turns true). */
+export function endHover(hover) {
+    triggerHoverEnd(hover, null, hover.state.pointerType);
+}
+/**
+ * Pointer hover interactions for an element; ignores emulated mouse events on touch devices.
+ * Spread `hoverProps` on the target.
+ */
+export function hoverProps(props = {}, dom) {
+    const hovered = signal(false);
+    // React Aria order: the hover callbacks run in the `pointerenter` handler chain, after an `onPointerEnter`
+    // merged before the bag (RAC: `mergeProps(DOMProps, …, hoverProps)`). With callbacks, or a pointer enter / leave
+    // handler in `dom` (Rivet: the bag the caller merges before this one), the bag is native `onPointerEnter` /
+    // `onPointerLeave`; otherwise (state only: nothing can observe the order) the delegated `onPointerOver`.
+    const native = !!(props.onHoverStart || props.onHoverEnd || props.onHoverChange || hasPointerEnterLeave(dom));
+    const hover = { props, hovered, native, state: { isHovered: false, pointerType: "", target: null, globals: [] } };
+    const bag = {};
+    if (native)
+        Object.assign(bag, {
+            onPointerEnter: (e) => hoverPointerEnter(hover, e),
+            onPointerLeave: (e) => hoverPointerLeave(hover, e),
+        });
+    else
+        Object.assign(bag, { onPointerOver: (e) => hoverPointerOver(hover, e) });
+    return { isHovered: hovered, hoverProps: bag };
+}
+/** Whether `dom` holds an `onPointerEnter` / `onPointerLeave` handler (own getters of live props unread: key only). */
+function hasPointerEnterLeave(dom) {
+    if (!dom)
+        return false;
+    for (const key of ["onPointerEnter", "onPointerLeave"]) {
+        const desc = Object.getOwnPropertyDescriptor(dom, key);
+        if (desc && (desc.get !== undefined || desc.value != null))
+            return true;
+    }
+    return false;
+}

package/interactions/index.d.ts

@@ -0,0 +1 @@
+export { controllable, controlledValue, setControlledValue, type ControlledState } from "./controllable.js";

package/interactions/index.js

@@ -0,0 +1,3 @@
+// Controlled / uncontrolled values (`controllable.ts`, react-stately useControlledState). (Prop merging:
+// `mergeProps` from `@rivetjs/cdk/utils` / `@rivetjs/cdk/interactions/merge-props` — one implementation.)
+export { controllable, controlledValue, setControlledValue } from "./controllable.js";

package/interactions/interact-outside.d.ts

@@ -0,0 +1,24 @@
+import type { Ref } from "@rivetjs/runtime/jsx-runtime";
+import { type MaybeAccessor } from "./utils.js";
+export interface InteractOutsideProps {
+    ref: Ref<Element> | (() => Element | null | undefined);
+    onInteractOutside?: (e: PointerEvent) => void;
+    onInteractOutsideStart?: (e: PointerEvent) => void;
+    /** Disable the outside interaction events (read at event time). */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+}
+/** Whether `event` is a primary-button interaction outside `element`. */
+export declare function isValidOutsideEvent(event: MouseEvent, element: Element | null | undefined): boolean;
+interface Outside {
+    props: InteractOutsideProps;
+    state: {
+        isPointerDown: boolean;
+    };
+}
+/** @internal capturing pointerdown listener of watchInteractOutside. */
+export declare function outsidePointerDown(outside: Outside, e: PointerEvent): void;
+/** @internal capturing click listener of watchInteractOutside (click, not pointerup: Android Chrome). */
+export declare function outsideClick(outside: Outside, e: PointerEvent): void;
+/** Call `onInteractOutside` when the user presses outside `ref` (dialogs, popovers). */
+export declare function watchInteractOutside(props: InteractOutsideProps): void;
+export {};

package/interactions/interact-outside.jsx

@@ -0,0 +1,57 @@
+// watchInteractOutside: pointer down + click outside an element (capturing, so a stopPropagation
+// inside the page does not hide it), ignoring non-primary buttons, targets removed from the document
+// and top-layer elements (`[data-rv-top-layer]`, e.g. toasts).
+// Ported from @react-aria/interactions useInteractOutside (react-spectrum), Apache-2.0, © Adobe;
+// portions from React (react-interactions), MIT, © Meta.
+//
+// Rivet: the document listeners are client events (`clientEvent(document, …, { capture: true })`):
+// a page using it boots the runtime at load and fetches the handler chunk on the first pointerdown.
+// `ref` is a `ref()` object (or an element accessor); `isDisabled` is read at event time.
+import { clientEvent } from "@rivetjs/runtime/dom";
+import { getEventTarget, nodeContains, read } from "./utils.js";
+/** Whether `event` is a primary-button interaction outside `element`. */
+export function isValidOutsideEvent(event, element) {
+    if (event.button > 0)
+        return false;
+    const target = getEventTarget(event);
+    if (target) {
+        // Target no longer in the document (removed by an earlier handler): ignore.
+        const doc = target.ownerDocument;
+        if (!doc || !nodeContains(doc.documentElement, target))
+            return false;
+        // Top-layer elements (toasts) are not "outside".
+        if (target.closest("[data-rv-top-layer]"))
+            return false;
+    }
+    if (!element)
+        return false;
+    // composedPath sees into open shadow roots.
+    return !event.composedPath().includes(element);
+}
+/** @internal capturing pointerdown listener of watchInteractOutside. */
+export function outsidePointerDown(outside, e) {
+    const { props, state } = outside;
+    if (read(props.isDisabled))
+        return;
+    if (props.onInteractOutside && isValidOutsideEvent(e, props.ref())) {
+        props.onInteractOutsideStart?.(e);
+        state.isPointerDown = true;
+    }
+}
+/** @internal capturing click listener of watchInteractOutside (click, not pointerup: Android Chrome). */
+export function outsideClick(outside, e) {
+    const { props, state } = outside;
+    if (read(props.isDisabled)) {
+        state.isPointerDown = false;
+        return;
+    }
+    if (state.isPointerDown && isValidOutsideEvent(e, props.ref()))
+        props.onInteractOutside?.(e);
+    state.isPointerDown = false;
+}
+/** Call `onInteractOutside` when the user presses outside `ref` (dialogs, popovers). */
+export function watchInteractOutside(props) {
+    const outside = { props, state: { isPointerDown: false } };
+    clientEvent(document, "pointerdown", (e) => outsidePointerDown(outside, e), { capture: true });
+    clientEvent(document, "click", (e) => outsideClick(outside, e), { capture: true });
+}

package/interactions/keyboard.d.ts

@@ -0,0 +1,28 @@
+import { type KeyboardShortcutBindings } from "../keys/index.js";
+import { type BaseEvent, type MaybeAccessor } from "./utils.js";
+export type { KeyboardShortcutBindings } from "../keys/index.js";
+/** The keyboard event handlers receive: native event + `continuePropagation()`. */
+export type RivetKeyboardEvent = BaseEvent<KeyboardEvent>;
+export interface KeyboardEvents {
+    onKeyDown?: (e: RivetKeyboardEvent) => void;
+    onKeyUp?: (e: RivetKeyboardEvent) => void;
+}
+export interface KeyboardProps extends KeyboardEvents {
+    /** Disable the keyboard events (read at event time). */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+    /** Keyboard shortcuts to handle (`{"Mod+s": (e) => save()}`). */
+    shortcuts?: KeyboardShortcutBindings;
+    /** Allow repeating keys (shortcuts only). */
+    allowRepeats?: boolean;
+    /** Allow composing keys (shortcuts only). */
+    allowComposing?: boolean;
+}
+export interface KeyboardResult {
+    keyboardProps: Record<string, unknown>;
+}
+/** @internal keydown handler of keyboardProps. */
+export declare function keyboardKeyDown(props: KeyboardProps, e: KeyboardEvent): void;
+/** @internal keyup handler of keyboardProps. */
+export declare function keyboardKeyUp(props: KeyboardProps, e: KeyboardEvent): void;
+/** Keyboard interactions for a focusable element. Spread `keyboardProps` on it. */
+export declare function keyboardProps(props?: KeyboardProps): KeyboardResult;

package/interactions/keyboard.jsx

@@ -0,0 +1,51 @@
+// keyboardProps: keydown / keyup handlers whose events stop propagating by default
+// (`continuePropagation()` opts out), plus declarative shortcuts.
+// Ported from @react-aria/interactions useKeyboard (react-spectrum), Apache-2.0, © Adobe.
+//
+// Rivet: handlers are resumable symbols; the event is the native KeyboardEvent augmented for the call
+// (`continuePropagation`, `isPropagationStopped`). Resumed pages: delegated dispatch runs only the
+// innermost handler of a type, so `continuePropagation()` reaches native ancestors' listeners but not
+// other resumed handlers (queued runtime work, see the parity spec).
+import { createKeyboardShortcutHandler } from "../keys/index.js";
+import { createEventHandler, getEventTarget, nodeContains, read } from "./utils.js";
+function shortcutSkip(props, e) {
+    // Not from a descendant (a portal): ignore.
+    if (!nodeContains(e.currentTarget, getEventTarget(e)))
+        return true;
+    return (e.repeat && !props.allowRepeats) || (e.isComposing && !props.allowComposing);
+}
+/** @internal keydown handler of keyboardProps. */
+export function keyboardKeyDown(props, e) {
+    if (read(props.isDisabled))
+        return;
+    const { shortcuts } = props;
+    if (!shortcuts)
+        return createEventHandler(props.onKeyDown)?.(e);
+    // chain(onKeyDown, shortcut handler): the user's handler sees the plain event first.
+    props.onKeyDown?.(e);
+    createEventHandler((event) => {
+        if (shortcutSkip(props, event))
+            return event.continuePropagation();
+        createKeyboardShortcutHandler(shortcuts)(event);
+    })(e);
+}
+/** @internal keyup handler of keyboardProps. */
+export function keyboardKeyUp(props, e) {
+    if (read(props.isDisabled))
+        return;
+    if (!props.shortcuts)
+        return createEventHandler(props.onKeyUp)?.(e);
+    props.onKeyUp?.(e);
+    // Shortcuts act on keydown only; keyup keeps propagating.
+    createEventHandler((event) => event.continuePropagation())(e);
+}
+/** Keyboard interactions for a focusable element. Spread `keyboardProps` on it. */
+export function keyboardProps(props = {}) {
+    // Separate object literals: R2 wraps object-literal function values, not conditional expressions.
+    const keyboardProps = {};
+    if (props.onKeyDown || props.shortcuts)
+        Object.assign(keyboardProps, { onKeyDown: (e) => keyboardKeyDown(props, e) });
+    if (props.onKeyUp || props.shortcuts)
+        Object.assign(keyboardProps, { onKeyUp: (e) => keyboardKeyUp(props, e) });
+    return { keyboardProps };
+}

package/interactions/long-press.d.ts

@@ -0,0 +1,41 @@
+import { type MaybeAccessor } from "./utils.js";
+import { type PressEvent } from "./press.jsx";
+export interface LongPressEvent extends Omit<PressEvent, "type" | "continuePropagation"> {
+    type: "longpressstart" | "longpressend" | "longpress";
+}
+export interface LongPressProps {
+    /** Disable long press events (read at event time). */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+    /** Which pointer type to listen for (default: mouse and touch). */
+    pointerType?: "mouse" | "touch";
+    /** Called when a long press interaction starts. */
+    onLongPressStart?: (e: LongPressEvent) => void;
+    /** Called when a long press interaction ends, over the target or when the pointer leaves it. */
+    onLongPressEnd?: (e: LongPressEvent) => void;
+    /** Called when the threshold time is met while the press is over the target. */
+    onLongPress?: (e: LongPressEvent) => void;
+    /** Milliseconds before a long press triggers (default 500). */
+    threshold?: number;
+    /** Description for assistive technology users, e.g. "Long press to open menu". */
+    accessibilityDescription?: string;
+}
+export interface LongPressResult {
+    /** Props to spread on the target (press handlers + `aria-describedby` when described). */
+    longPressProps: Record<string, unknown>;
+    /** The id the description element must carry, or undefined (no description / no onLongPress). */
+    descriptionId?: string;
+}
+interface LongPress {
+    props: LongPressProps;
+    state: {
+        timer: ReturnType<typeof setTimeout> | undefined;
+        globals: (() => void)[];
+    };
+}
+/** @internal onPressStart of longPressProps. */
+export declare function longPressStart(lp: LongPress, e: PressEvent): void;
+/** @internal onPressEnd of longPressProps. */
+export declare function longPressEnd(lp: LongPress, e: PressEvent): void;
+/** Long press interactions across mouse and touch devices. */
+export declare function longPressProps(props?: LongPressProps): LongPressResult;
+export {};