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

package/interactions/pressable.jsx

@@ -0,0 +1,93 @@
+// Ported from react-aria Pressable, PressResponder, ClearPressResponder
+// (packages/react-aria/src/interactions/Pressable.tsx, PressResponder.tsx, context.ts), Apache-2.0, © Adobe.
+// Rivet:
+// - `PressResponder` provides `PressResponderContext` (press.tsx, resumable id `rv-press-responder`):
+//   the nearest `pressProps` below merges those props (handlers chain, parent first) and calls `register`.
+//   Its children render into a const before the provider returns, so the dev warning "rendered without
+//   a pressable child" is a synchronous check after them on client renders (no effect). Server renders
+//   never warn (RA warns in a `useEffect`, which never runs in SSR): server templates call slot-valued
+//   holes (`<div>{props.children}</div>`) while serializing, after the check, so a trigger passed through
+//   a wrapper registers too late (HeroUI ColorPicker root). `register` is an inline arrow over a plain
+//   state object (resumable).
+// - `ref`: the responder's ref, else the outer responder's (RA `useObjectRef(ref || prevContext?.ref)` +
+//   `useSyncRef`), merged with `mergeRefValues`.
+// - Deviation: `<Pressable>` cannot clone its child (compiled templates): the child is a render function
+//   receiving the merged press + focusable props to spread on its element, passing `ref`
+//   explicitly (`{(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 { untrack, useContext } from "@rivetjs/reactivity";
+import { Provider as ContextProvider, clientEffect, ref as createRef } from "@rivetjs/runtime/dom";
+import { renderSlot } from "@rivetjs/runtime/slot";
+import { focusableProps } from "../focus/focusable.jsx";
+import { mergeRefValues } from "../slots/index.jsx";
+import { mergeProps } from "./merge-props.jsx";
+import { PressResponderContext, pressProps } from "./press.jsx";
+import { isFocusable } from "./utils.js";
+export { PressResponderContext } from "./press.jsx";
+const isDev = () => globalThis.process?.env?.NODE_ENV === "development";
+/** Passes press props to the nearest pressable child (`pressProps`) through context (RA `PressResponder`). */
+export function PressResponder(props) {
+    const { children, ref, ...rest } = props;
+    const prevContext = useContext(PressResponderContext);
+    const state = { isRegistered: false };
+    const context = mergeProps(prevContext || {}, {
+        ...rest,
+        register: () => {
+            state.isRegistered = true;
+            if (prevContext)
+                prevContext.register?.();
+        },
+    });
+    context.ref = mergeRefValues(ref, prevContext?.ref);
+    return (<ContextProvider token={PressResponderContext} value={context}>
+      {renderResponderChildren(children, state)}
+    </ContextProvider>);
+}
+function renderResponderChildren(children, state) {
+    const content = renderSlot(children);
+    if (!state.isRegistered && typeof document !== "undefined" && isDev()) {
+        console.warn("A PressResponder was rendered without a pressable child. Either spread pressProps, or wrap your DOM node with <Pressable> component.");
+        state.isRegistered = true;
+    }
+    return content;
+}
+/** Stops press props of outer `PressResponder`s from reaching the children (RA `ClearPressResponder`). */
+export function ClearPressResponder(props) {
+    const children = props.children;
+    const context = { register: () => { } };
+    return (<ContextProvider token={PressResponderContext} value={context}>
+      {renderSlot(children)}
+    </ContextProvider>);
+}
+const INTERACTIVE_ROLES = /^(application|button|checkbox|combobox|gridcell|link|menuitem|menuitemcheckbox|menuitemradio|option|radio|searchbox|separator|slider|spinbutton|switch|tab|textbox|treeitem)$/;
+/** Makes its child pressable and focusable (RA `<Pressable>`); see the header for the render-function child. */
+export function Pressable(props) {
+    const { children, ref, ...options } = props;
+    // RA usePress syncs the responder's ref with the pressable element (`useSyncRef(context, ref)`).
+    const responder = useContext(PressResponderContext);
+    const element = mergeRefValues(ref ?? createRef(), responder?.ref);
+    const press = pressProps(options);
+    const focusable = focusableProps(options, element);
+    const merged = mergeProps(press.pressProps, focusable);
+    merged.ref = focusable.ref ?? element;
+    if (isDev()) {
+        const isDisabled = options.isDisabled;
+        clientEffect(() => {
+            const el = typeof element === "function" ? element() : element.current;
+            if (!el)
+                return console.error("<Pressable> child must forward its ref to a DOM element.");
+            untrack(() => {
+                if (!isDisabled && !isFocusable(el, { skipVisibilityCheck: true }))
+                    return console.warn("<Pressable> child must be focusable. Please ensure the tabIndex prop is passed through.");
+                if (!/^(button|input|select|textarea|a|area|summary)$/.test(el.localName)) {
+                    const role = el.getAttribute("role");
+                    if (!role)
+                        console.warn("<Pressable> child must have an interactive ARIA role.");
+                    else if (!INTERACTIVE_ROLES.test(role))
+                        console.warn(`<Pressable> child must have an interactive ARIA role. Got "${role}".`);
+                }
+            });
+        });
+    }
+    return renderSlot(children, merged);
+}

package/interactions/scroll-wheel.d.ts

@@ -0,0 +1,20 @@
+import type { Ref } from "@rivetjs/runtime/jsx-runtime";
+import { type MaybeAccessor } from "./utils.js";
+export interface ScrollEvent {
+    deltaX: number;
+    deltaY: number;
+}
+export interface ScrollWheelProps {
+    onScroll?: (e: ScrollEvent) => void;
+    /** Disable the listener (read at event time). */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+}
+/** @internal wheel handler of scrollWheelProps. */
+export declare function scrollWheel(props: ScrollWheelProps, e: WheelEvent): void;
+/**
+ * Scroll wheel events for an element. With `ref`: a non-passive listener on the element (client
+ * effect); without: spread `scrollWheelProps` (`onWheel`).
+ */
+export declare function scrollWheelProps(props: ScrollWheelProps, ref?: Ref<HTMLElement> | (() => HTMLElement | null | undefined)): {
+    scrollWheelProps: Record<string, unknown>;
+};

package/interactions/scroll-wheel.jsx

@@ -0,0 +1,40 @@
+// scrollWheelProps: wheel deltas as scroll events, page scroll prevented (Ctrl+wheel = zoom: ignored).
+// Ported from @react-aria/interactions useScrollWheel (react-spectrum), Apache-2.0, © Adobe.
+//
+// Deviation: the original attaches a non-passive listener to a ref in an effect. Rivet returns the
+// handler as `scrollWheelProps.onWheel`; delegated resumed listeners for `wheel` are passive (scroll
+// performance), so on resumed pages preventDefault takes effect once the element's own listener is
+// bound by a client render, or use `useScrollWheel(props, ref)` which also registers a non-passive
+// client listener on `ref` (runtime boot at load).
+import { clientEffect } from "@rivetjs/runtime/dom";
+import { read } from "./utils.js";
+/** @internal wheel handler of scrollWheelProps. */
+export function scrollWheel(props, e) {
+    if (read(props.isDisabled))
+        return;
+    // Ctrl + wheel is a zoom gesture.
+    if (e.ctrlKey)
+        return;
+    // Stop scrolling the page.
+    e.preventDefault();
+    e.stopPropagation();
+    props.onScroll?.({ deltaX: e.deltaX, deltaY: e.deltaY });
+}
+/**
+ * Scroll wheel events for an element. With `ref`: a non-passive listener on the element (client
+ * effect); without: spread `scrollWheelProps` (`onWheel`).
+ */
+export function scrollWheelProps(props, ref) {
+    if (ref) {
+        clientEffect(() => {
+            const element = ref();
+            if (!element)
+                return;
+            const listener = (e) => scrollWheel(props, e);
+            element.addEventListener("wheel", listener, { passive: false });
+            return () => element.removeEventListener("wheel", listener);
+        });
+        return { scrollWheelProps: {} };
+    }
+    return { scrollWheelProps: { onWheel: (e) => scrollWheel(props, e) } };
+}

package/interactions/utils.d.ts

@@ -0,0 +1,52 @@
+export { isAndroid, isChrome, isFirefox, isIOS, isIPad, isIPhone, isMac, isWebKit, isVirtualClick, isVirtualPointerEvent } from "../platform/index.js";
+export { getActiveElement, getOwnerDocument, getOwnerWindow, isFocusWithin, isShadowRoot, nodeContains } from "../utils/dom.js";
+export { focusWithoutScrolling, runAfterTransition } from "../utils/transitions.js";
+export { linkState } from "../utils/link-state.js";
+export type PointerType = "mouse" | "pen" | "touch" | "keyboard" | "virtual";
+export type FocusableElement = HTMLElement | SVGElement;
+/** A value or an accessor of it (signals qualify): options are read at event time. */
+export type MaybeAccessor<T> = T | (() => T);
+/** Read a `MaybeAccessor` (functions are called; signals are functions). */
+export declare function read<T>(value: MaybeAccessor<T>): T;
+/** The event's real target (`../utils/dom.ts` `getEventTarget`), typed for the hooks (an `Element` unless told otherwise). */
+export declare function getEventTarget<T = Element>(event: Event): T;
+export declare const FOCUSABLE_ELEMENT_SELECTOR: string;
+export declare const TABBABLE_ELEMENT_SELECTOR: string;
+/** Rendered and visible (`checkVisibility` where supported, else styles + `hidden` + closed `<details>`). */
+export declare function isElementVisible(element: Element, child?: Element): boolean;
+/** react-aria `isFocusable`: matches the focusable selector, not inert, visible (unless skipped). */
+export declare function isFocusable(element: Element, options?: {
+    skipVisibilityCheck?: boolean;
+}): boolean;
+/** react-aria `isTabbable`: matches the tabbable selector, visible, not inert. */
+export declare function isTabbable(element: Element): boolean;
+export declare function disableTextSelection(target?: Element): void;
+export declare function restoreTextSelection(target?: Element): void;
+/** `<input type>`s that take no text (upstream declares this set in usePress and useFocusVisible each; one copy here). */
+export declare const nonTextInputTypes: ReadonlySet<string>;
+/** Set while `preventFocus` swallows the focus events it causes (focus-visible ignores them). */
+export declare const focusGuard: {
+    ignore: boolean;
+};
+/**
+ * Prevent the focus that the current mousedown would cause on `target` (or its nearest focusable
+ * ancestor) without `preventDefault()` (which would also stop text selection / drag): let the
+ * browser move focus, swallow the events, and move focus back. Returns a cleanup function.
+ */
+export declare function preventFocus(target: FocusableElement | null): (() => void) | undefined;
+/** A native event with react-aria's propagation API: stopped by default, `continuePropagation()` opts out. */
+export type BaseEvent<E extends Event> = E & {
+    /** @deprecated stopPropagation is the default; call `continuePropagation()` to let the event bubble. */
+    stopPropagation(): void;
+    continuePropagation(): void;
+    isPropagationStopped(): boolean;
+};
+/**
+ * Wrap an event handler so propagation stops by default and `continuePropagation()` lets the event
+ * through (react-aria `createEventHandler`). The handler gets the native event, augmented in place for
+ * the call (`continuePropagation`, `isPropagationStopped`; `stopPropagation` only marks it); nested
+ * wrappers chain, so an inner `continuePropagation()` also continues the outer one.
+ */
+export declare function createEventHandler<E extends Event>(handler?: (e: BaseEvent<E>) => void): ((e: E) => void) | undefined;
+/** The global document in a browser, `null` on the server (for code that also runs while rendering). */
+export declare const browserDocument: () => Document | null;

package/interactions/utils.js

@@ -0,0 +1,253 @@
+// Shared helpers of the interaction hooks: virtual click detection, focusability selectors,
+// preventFocus, text selection, createEventHandler, `read` / `MaybeAccessor`.
+// Ported from @react-aria/interactions + @react-aria/utils (react-spectrum), Apache-2.0, © Adobe.
+// Browser-only bodies; nothing runs at import time.
+//
+// One implementation per helper: platform probes come from `../platform` (return `undefined` on the
+// server), DOM / shadow-DOM functions from `../utils/dom.ts`, `runAfterTransition` /
+// `focusWithoutScrolling` from the leaf `../utils/transitions.ts`, `linkState` from the leaf
+// `../utils/link-state.ts` (the flag usePress and focus-visible read is the one `openLink` sets).
+// They are re-exported here for the hooks. Leaves only (DOCS-COLD 2026-10-20): `chain` (`./merge-props.tsx`)
+// and `openLink` (`../utils/links.tsx`) are imported from their modules, so a focus / overlay helper
+// importing this file does not pull prop merging or the router module into its chunk.
+import { getEventTarget as domEventTarget } from "../utils/dom.js";
+import { isIOS, isWebKit } from "../platform/index.js";
+import { getActiveElement, getOwnerDocument, getOwnerWindow, isShadowRoot, nodeContains } from "../utils/dom.js";
+import { focusWithoutScrolling, runAfterTransition } from "../utils/transitions.js";
+export { isAndroid, isChrome, isFirefox, isIOS, isIPad, isIPhone, isMac, isWebKit, isVirtualClick, isVirtualPointerEvent } from "../platform/index.js";
+export { getActiveElement, getOwnerDocument, getOwnerWindow, isFocusWithin, isShadowRoot, nodeContains } from "../utils/dom.js";
+export { focusWithoutScrolling, runAfterTransition } from "../utils/transitions.js";
+export { linkState } from "../utils/link-state.js";
+/** Read a `MaybeAccessor` (functions are called; signals are functions). */
+export function read(value) {
+    return typeof value === "function" ? value() : value;
+}
+/** The event's real target (`../utils/dom.ts` `getEventTarget`), typed for the hooks (an `Element` unless told otherwise). */
+export function getEventTarget(event) {
+    return domEventTarget(event);
+}
+// --- Focusability (react-aria selectors) --------------------------------------------------------------
+const focusableElements = [
+    "input:not([disabled]):not([type=hidden])",
+    "select:not([disabled])",
+    "textarea:not([disabled])",
+    "button:not([disabled])",
+    "a[href]",
+    "area[href]",
+    "summary",
+    "iframe",
+    "object",
+    "embed",
+    "audio[controls]",
+    "video[controls]",
+    '[contenteditable]:not([contenteditable^="false"])',
+    "permission",
+];
+export const FOCUSABLE_ELEMENT_SELECTOR = focusableElements.join(":not([hidden]),") + ",[tabindex]:not([disabled]):not([hidden])";
+export const TABBABLE_ELEMENT_SELECTOR = [...focusableElements, '[tabindex]:not([tabindex="-1"]):not([disabled])'].join(':not([hidden]):not([tabindex="-1"]),');
+function isStyleVisible(element) {
+    const win = getOwnerWindow(element);
+    if (!(element instanceof win.HTMLElement) && !(element instanceof win.SVGElement))
+        return false;
+    const { display, visibility } = element.style;
+    let visible = display !== "none" && visibility !== "hidden" && visibility !== "collapse";
+    if (visible) {
+        const computed = win.getComputedStyle(element);
+        visible = computed.display !== "none" && computed.visibility !== "hidden" && computed.visibility !== "collapse";
+    }
+    return visible;
+}
+/** Rendered and visible (`checkVisibility` where supported, else styles + `hidden` + closed `<details>`). */
+export function isElementVisible(element, child) {
+    if (typeof element.checkVisibility === "function")
+        return element.checkVisibility({ visibilityProperty: true }) && !element.closest("[data-rv-prevent-focus]");
+    return (element.nodeName !== "#comment" &&
+        isStyleVisible(element) &&
+        !element.hasAttribute("hidden") &&
+        !element.hasAttribute("data-rv-prevent-focus") &&
+        (element.nodeName === "DETAILS" && child && child.nodeName !== "SUMMARY" ? element.hasAttribute("open") : true) &&
+        (!element.parentElement || isElementVisible(element.parentElement, element)));
+}
+function isInert(element) {
+    for (let node = element; node; node = node.parentElement)
+        if (node.inert)
+            return true;
+    return false;
+}
+/** react-aria `isFocusable`: matches the focusable selector, not inert, visible (unless skipped). */
+export function isFocusable(element, options) {
+    return element.matches(FOCUSABLE_ELEMENT_SELECTOR) && !isInert(element) && (!!options?.skipVisibilityCheck || isElementVisible(element));
+}
+/** react-aria `isTabbable`: matches the tabbable selector, visible, not inert. */
+export function isTabbable(element) {
+    return element.matches(TABBABLE_ELEMENT_SELECTOR) && isElementVisible(element) && !isInert(element);
+}
+let selectionState = "default";
+let savedUserSelect = "";
+const modifiedElements = new WeakMap();
+export function disableTextSelection(target) {
+    if (isIOS() && isWebKit()) {
+        if (selectionState === "default") {
+            const style = getOwnerDocument(target).documentElement.style;
+            savedUserSelect = style.webkitUserSelect;
+            style.webkitUserSelect = "none";
+        }
+        selectionState = "disabled";
+    }
+    else if (target instanceof HTMLElement || target instanceof SVGElement) {
+        const style = target.style;
+        const property = "userSelect" in style ? "userSelect" : "webkitUserSelect";
+        modifiedElements.set(target, style[property]);
+        style[property] = "none";
+    }
+}
+export function restoreTextSelection(target) {
+    if (isIOS() && isWebKit()) {
+        if (selectionState !== "disabled")
+            return;
+        selectionState = "restoring";
+        // iOS may still select right after pointer up: wait, then let transitions finish.
+        setTimeout(() => {
+            runAfterTransition(() => {
+                if (selectionState === "restoring") {
+                    const style = getOwnerDocument(target).documentElement.style;
+                    if (style.webkitUserSelect === "none")
+                        style.webkitUserSelect = savedUserSelect || "";
+                    savedUserSelect = "";
+                    selectionState = "default";
+                }
+            });
+        }, 300);
+    }
+    else if ((target instanceof HTMLElement || target instanceof SVGElement) && modifiedElements.has(target)) {
+        const old = modifiedElements.get(target);
+        const style = target.style;
+        const property = "userSelect" in style ? "userSelect" : "webkitUserSelect";
+        if (style[property] === "none")
+            style[property] = old;
+        if (target.getAttribute("style") === "")
+            target.removeAttribute("style");
+        modifiedElements.delete(target);
+    }
+}
+/** `<input type>`s that take no text (upstream declares this set in usePress and useFocusVisible each; one copy here). */
+export const nonTextInputTypes = new Set(["checkbox", "radio", "range", "color", "file", "image", "button", "submit", "reset"]);
+// --- preventFocus ----------------------------------------------------------------------------------
+/** Set while `preventFocus` swallows the focus events it causes (focus-visible ignores them). */
+export const focusGuard = { ignore: false };
+/**
+ * Prevent the focus that the current mousedown would cause on `target` (or its nearest focusable
+ * ancestor) without `preventDefault()` (which would also stop text selection / drag): let the
+ * browser move focus, swallow the events, and move focus back. Returns a cleanup function.
+ */
+export function preventFocus(target) {
+    while (target && !isFocusable(target, { skipVisibilityCheck: true }))
+        target = target.parentElement;
+    const win = getOwnerWindow(target);
+    const active = getActiveElement(win.document);
+    if (!active || active === target)
+        return;
+    const targetRoot = target?.getRootNode();
+    const root = targetRoot != null && isShadowRoot(targetRoot) ? targetRoot : win;
+    const movingToTarget = (node) => node === target || (!!node && nodeContains(target, node));
+    const fromActive = (node) => node === active || (!!node && nodeContains(active, node));
+    focusGuard.ignore = true;
+    let refocusing = false;
+    const onBlur = (e) => {
+        if (fromActive(getEventTarget(e)) || refocusing)
+            e.stopImmediatePropagation();
+    };
+    const onFocusOut = (e) => {
+        if (fromActive(getEventTarget(e)) || refocusing) {
+            e.stopImmediatePropagation();
+            // No focusable ancestor: no focus event follows; restore now.
+            if (!target && !refocusing) {
+                refocusing = true;
+                focusWithoutScrolling(active);
+                cleanup();
+            }
+        }
+    };
+    const onFocus = (e) => {
+        if (movingToTarget(getEventTarget(e)) || refocusing)
+            e.stopImmediatePropagation();
+    };
+    const onFocusIn = (e) => {
+        if (movingToTarget(getEventTarget(e)) || refocusing) {
+            e.stopImmediatePropagation();
+            if (!refocusing) {
+                refocusing = true;
+                focusWithoutScrolling(active);
+                cleanup();
+            }
+        }
+    };
+    root.addEventListener("blur", onBlur, true);
+    root.addEventListener("focusout", onFocusOut, true);
+    root.addEventListener("focusin", onFocusIn, true);
+    root.addEventListener("focus", onFocus, true);
+    const cleanup = () => {
+        cancelAnimationFrame(raf);
+        root.removeEventListener("blur", onBlur, true);
+        root.removeEventListener("focusout", onFocusOut, true);
+        root.removeEventListener("focusin", onFocusIn, true);
+        root.removeEventListener("focus", onFocus, true);
+        focusGuard.ignore = false;
+        refocusing = false;
+    };
+    const raf = requestAnimationFrame(cleanup);
+    return cleanup;
+}
+/**
+ * Wrap an event handler so propagation stops by default and `continuePropagation()` lets the event
+ * through (react-aria `createEventHandler`). The handler gets the native event, augmented in place for
+ * the call (`continuePropagation`, `isPropagationStopped`; `stopPropagation` only marks it); nested
+ * wrappers chain, so an inner `continuePropagation()` also continues the outer one.
+ */
+export function createEventHandler(handler) {
+    if (!handler)
+        return undefined;
+    return (e) => {
+        let shouldStop = true;
+        const own = e;
+        const outer = {
+            continuePropagation: Object.getOwnPropertyDescriptor(e, "continuePropagation"),
+            isPropagationStopped: Object.getOwnPropertyDescriptor(e, "isPropagationStopped"),
+            stopPropagation: Object.getOwnPropertyDescriptor(e, "stopPropagation"),
+        };
+        const outerContinue = own.continuePropagation;
+        Object.defineProperties(e, {
+            continuePropagation: {
+                configurable: true,
+                value: () => {
+                    shouldStop = false;
+                    outerContinue?.call(e);
+                },
+            },
+            isPropagationStopped: { configurable: true, value: () => shouldStop },
+            stopPropagation: {
+                configurable: true,
+                value: () => {
+                    shouldStop = true;
+                },
+            },
+        });
+        try {
+            handler(e);
+        }
+        finally {
+            for (const key of ["continuePropagation", "isPropagationStopped", "stopPropagation"]) {
+                const descriptor = outer[key];
+                if (descriptor)
+                    Object.defineProperty(e, key, descriptor);
+                else
+                    delete e[key];
+            }
+        }
+        // Nested wrappers: the outer one decides (it reads the inner result through continuePropagation).
+        if (shouldStop && !outer.isPropagationStopped && !e.cancelBubble)
+            e.stopPropagation();
+    };
+}
+/** The global document in a browser, `null` on the server (for code that also runs while rendering). */
+export const browserDocument = () => (typeof document === "undefined" ? null : document);

package/keyboard/index.d.ts

@@ -0,0 +1,12 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import { type DOMRenderProps } from "../utils/render.js";
+import { type ContextValue, type HTMLProps, type RefValue, type SlotProps, type StyleObject } from "../slots/index.jsx";
+export interface KeyboardProps extends HTMLProps<"kbd">, SlotProps, DOMRenderProps<"kbd", undefined> {
+    class?: string;
+    style?: StyleObject;
+    ref?: RefValue<HTMLElement>;
+    /** Content; a function (not lazy JSX) is reactive content, rendered in a binding (e.g. a context-provided `children: () => title`). */
+    children?: Content | (() => Content);
+}
+export declare const KeyboardContext: import("@rivetjs/reactivity").Context<ContextValue<KeyboardProps, HTMLElement>>;
+export declare function Keyboard(props: KeyboardProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement | null;

package/keyboard/index.jsx

@@ -0,0 +1,34 @@
+// Ported from react-aria-components Keyboard (packages/react-aria-components/src/Keyboard.tsx), Apache-2.0, © Adobe.
+// A keyboard shortcut (`<kbd dir="ltr">`); menu items provide `KeyboardContext` (slot `keyboard`).
+// Rivet: props merged with `KeyboardContext` (`contextProps`). `render` (RAC DOMRenderProps): given, the attributes object (`ref`, `class`, `style`, `children`) goes to `render(attrs, undefined)` instead of the default element; the default path is the compiled element.
+import { createContext } from "@rivetjs/reactivity";
+import { renderSlot } from "@rivetjs/runtime/slot";
+import { slotChildren } from "../utils/render.js";
+import { resumableContext, contextProps, probeSlot, } from "../slots/index.jsx";
+import { isHiddenPart } from "../collections/hidden.js";
+import { slotProbing } from "#server";
+export const KeyboardContext = resumableContext(createContext({}, { id: "rv-keyboard" }));
+export function Keyboard(props) {
+    // A menu item's server slot probe (`probeSlots`): mark the shortcut slot id this part takes, render nothing.
+    if (slotProbing)
+        return (probeSlot(props, KeyboardContext), null);
+    // RAC createHideableComponent: nothing in the collection build pass (its context providers are absent).
+    if (isHiddenPart())
+        return null;
+    const [merged, ref] = contextProps(props, props.ref, KeyboardContext);
+    const { children, class: className, style, slot, dir = "ltr", render, ...domProps } = merged;
+    const s = slot ?? undefined;
+    if (render)
+        return render({
+            ...domProps,
+            style: (typeof style === "function" ? style() : style),
+            dir,
+            slot: s,
+            ref: ref,
+            class: className,
+            children: slotChildren(children),
+        }, undefined);
+    return (<kbd {...domProps} style={(typeof style === "function" ? style() : style)} dir={dir} slot={s} ref={ref} class={className}>
+      {renderSlot(children)}
+    </kbd>);
+}

package/keys/index.d.ts

@@ -0,0 +1,68 @@
+import type { Direction } from "../bidi/index.js";
+export type Orientation = "vertical" | "horizontal" | "both";
+export interface NavigationOptions {
+    /** Arrow keys that move: vertical = Up/Down, horizontal = Left/Right, both = all four (default vertical). */
+    orientation?: Orientation;
+    /** Wrap from the last item to the first and back (default false). */
+    wrap?: boolean;
+    /** Home / End move to the first / last item (default true). */
+    homeEnd?: boolean;
+    /** PageUp / PageDown step (items); 0 = not handled (default 0). */
+    pageSize?: number;
+    /** Text direction for horizontal arrows (default ltr). */
+    dir?: Direction;
+    /** Skip items for which this returns true. */
+    isDisabled?: (index: number) => boolean;
+}
+/** Keys `nextIndex` may handle for `options`, as a `data-rk` value (loader holds them while a chunk loads). */
+export declare function navigationKeys(options?: NavigationOptions): string;
+/**
+ * Index the key moves to from `from` (-1: nothing focused yet) among `count` items, or `null` when
+ * the key is not a navigation key for these options (let it through). Returns `from` when the key is
+ * handled but nothing moves (at the edge without wrap).
+ */
+export declare function nextIndex(count: number, from: number, key: string, options?: NavigationOptions): number | null;
+/**
+ * Typeahead (APG): printable `key` extends the owner's buffer (reset after 750 ms); returns the index
+ * of the next item after `from` whose text starts with the buffer (base sensitivity: case and accents
+ * ignored, `Intl.Collator`), or -1. Repeating one character cycles through items starting with it.
+ * `owner` is any object identifying the widget (its state object).
+ */
+export declare function typeahead(owner: object, texts: readonly string[], from: number, key: string, now?: number, isDisabled?: (index: number) => boolean): number;
+/** Test hook: forget an owner's typeahead buffer. */
+export declare function _resetTypeahead(owner: object): void;
+/** A shortcut action: `undefined` / `true` = handled (preventDefault, stop); `false` = not handled. */
+export type KeyboardShortcutAction = (e: KeyboardEvent & {
+    continuePropagation?: () => void;
+}) => void | boolean | Partial<{
+    shouldContinuePropagation?: boolean;
+    shouldPreventDefault?: boolean;
+}>;
+/** Shortcut strings (`"Mod+s"`, `"Control+Shift+a"`, `"Escape"`) → actions. */
+export type KeyboardShortcutBindings = Record<string, KeyboardShortcutAction>;
+export interface ParsedKeyboardShortcut {
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    /** Platform primary: Cmd on Mac, Control elsewhere. */
+    mod: boolean;
+    key: string;
+}
+/** Canonical modifier tokens of a binding (`Mod` → Meta on Mac, Control elsewhere). */
+export declare function modifierSetFromParsed(parsed: ParsedKeyboardShortcut): Set<string>;
+/** Modifier tokens of a keydown event. */
+export declare function modifierSetFromEvent(e: KeyboardEvent): Set<string>;
+/** Parse `"Mod+Shift+z"`, `"Ctrl+Alt+Enter"`, `"Escape"` (modifiers case-insensitive, any order). */
+export declare function parseKeyboardShortcut(spec: string): ParsedKeyboardShortcut;
+/** Canonical form of a binding: modifiers sorted (Alt, Control, Meta, Shift), then the key. */
+export declare function canonicalKeyboardShortcut(parsed: ParsedKeyboardShortcut): string;
+/** Canonical form of a keydown event. */
+export declare function keyboardEventToCanonicalShortcut(e: KeyboardEvent): string;
+/**
+ * A keydown handler running the action of the exact modifier + key match (later duplicate bindings
+ * win). Handled: preventDefault + stop; unhandled keys `continuePropagation()` when available.
+ */
+export declare function createKeyboardShortcutHandler(bindings: KeyboardShortcutBindings): (e: KeyboardEvent & {
+    continuePropagation?: () => void;
+}) => void;