@octanejs/aria 0.0.1

package/src/interactions/useFocusable.ts

@@ -0,0 +1,205 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/interactions/useFocusable.tsx).
+// octane adaptations:
+// - React's `forwardRef` becomes octane's ref-as-prop: `FocusableProvider` and `Focusable`
+//   read the forwarded ref from props.
+// - Components are built with `createElement`; `Focusable` re-projects its child with
+//   octane's `cloneElement`/`isValidElement`/`Children` (they operate on element
+//   DESCRIPTORS — prop-position JSX / createElement results). Non-element children render
+//   unchanged (upstream's dev-warning path, without the warning).
+// - The composed child ref is memoized (upstream builds `mergeRefs(...)` fresh per render);
+//   a fresh identity would make octane detach/re-attach the child's ref every render (see
+//   the radix Slot note on ref churn).
+// - Upstream's dev-only console warning effect (ref/focusable/ARIA-role checks) is not ported.
+// - `FocusableProps` / `DOMAttributes` from '@react-types/shared' drag React event types;
+//   local structural equivalents (built on the ported FocusEvents/KeyboardEvents) replace them.
+import type { FocusableDOMProps, FocusableElement, RefObject } from '@react-types/shared';
+import {
+	Children,
+	cloneElement,
+	createContext,
+	createElement,
+	isValidElement,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+} from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { focusSafely } from './focusSafely';
+import { mergeProps } from '../utils/mergeProps';
+import { mergeRefs, type MergableRef } from '../utils/mergeRefs';
+import { useFocus, type FocusEvents } from './useFocus';
+import { useKeyboard, type KeyboardEvents } from './useKeyboard';
+import { useObjectRef } from '../utils/useObjectRef';
+import { useSyncRef } from '../utils/useSyncRef';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React attribute types).
+export type DOMAttributes = Record<string, any>;
+
+// octane adaptation: local structural FocusableProps (upstream's is typed over React events).
+export interface FocusableProps<Target = FocusableElement>
+	extends FocusEvents<Target>, KeyboardEvents {
+	/** Whether the element should receive focus on render. */
+	autoFocus?: boolean;
+}
+
+type MutableRefObject<T> = { current: T };
+
+export interface FocusableOptions<T = FocusableElement>
+	extends FocusableProps<T>, FocusableDOMProps {
+	/** Whether focus should be disabled. */
+	isDisabled?: boolean;
+}
+
+export interface FocusableProviderProps extends DOMAttributes {
+	/** The child element to provide DOM props to. */
+	children?: any;
+}
+
+interface FocusableContextValue extends FocusableProviderProps {
+	ref?: MutableRefObject<FocusableElement | null>;
+}
+
+// Exported for collections, which forwards this context.
+/** @private */
+export let FocusableContext = createContext<FocusableContextValue | null>(null);
+
+function useFocusableContext(
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): FocusableContextValue {
+	let context = useContext(FocusableContext) || {};
+	useSyncRef(context, ref, subSlot(slot, 'sync'));
+
+	let { ref: _, ...otherProps } = context;
+	return otherProps;
+}
+
+/**
+ * Provides DOM props to the nearest focusable child.
+ */
+export function FocusableProvider(
+	props: FocusableProviderProps & { ref?: MergableRef<FocusableElement> },
+): any {
+	const slot = S('FocusableProvider');
+	let { children, ref, ...otherProps } = props;
+	let objRef = useObjectRef<FocusableElement>(ref, subSlot(slot, 'objRef'));
+	let context = {
+		...otherProps,
+		ref: objRef,
+	};
+
+	return createElement(FocusableContext.Provider, { value: context, children });
+}
+
+export interface FocusableAria {
+	/** Props for the focusable element. */
+	focusableProps: DOMAttributes;
+}
+
+/**
+ * Used to make an element focusable and capable of auto focus.
+ */
+export function useFocusable<T extends FocusableElement = FocusableElement>(
+	props: FocusableOptions<T>,
+	domRef: RefObject<FocusableElement | null>,
+): FocusableAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useFocusable<T extends FocusableElement = FocusableElement>(
+	props: FocusableOptions<T>,
+	domRef: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): FocusableAria;
+export function useFocusable(...args: any[]): FocusableAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFocusable');
+	const props = user[0] as FocusableOptions;
+	const domRef = user[1] as RefObject<FocusableElement | null>;
+
+	let { focusProps } = useFocus(props, subSlot(slot, 'focus'));
+	let { keyboardProps } = useKeyboard(props, subSlot(slot, 'keyboard'));
+	let interactions = mergeProps(focusProps, keyboardProps);
+	let domProps = useFocusableContext(domRef, subSlot(slot, 'context'));
+	let interactionProps = props.isDisabled ? {} : domProps;
+	let autoFocusRef = useRef(props.autoFocus, subSlot(slot, 'autoFocus'));
+
+	useEffect(
+		() => {
+			if (autoFocusRef.current && domRef.current) {
+				focusSafely(domRef.current);
+			}
+			autoFocusRef.current = false;
+		},
+		[domRef],
+		subSlot(slot, 'autoFocusEffect'),
+	);
+
+	// Always set a tabIndex so that Safari allows focusing native buttons and inputs.
+	let tabIndex: number | undefined = props.excludeFromTabOrder ? -1 : 0;
+	if (props.isDisabled) {
+		tabIndex = undefined;
+	}
+
+	return {
+		focusableProps: mergeProps(
+			{
+				...interactions,
+				tabIndex,
+			},
+			interactionProps,
+		),
+	};
+}
+
+export interface FocusableComponentProps extends FocusableOptions {
+	children: any;
+}
+
+export function Focusable(
+	props: FocusableComponentProps & { ref?: MergableRef<FocusableElement> },
+): any {
+	const slot = S('Focusable');
+	let { children, ref: forwardedRef, ...otherProps } = props;
+	let ref = useObjectRef<FocusableElement>(forwardedRef, subSlot(slot, 'objRef'));
+	let { focusableProps } = useFocusable(otherProps, ref, subSlot(slot, 'focusable'));
+
+	// octane adaptation: upstream's dev-only console warning effect (Element ref /
+	// isFocusable / interactive-ARIA-role checks) is not ported.
+
+	// Resolve the single element child. octane children arrive as descriptors from
+	// prop-position JSX / createElement; a single-element array unwraps (octane
+	// convention — see radix Slot).
+	let target: any = children;
+	if (Array.isArray(children)) {
+		const arr = Children.toArray(children);
+		if (arr.length === 1) {
+			target = arr[0];
+		}
+	}
+
+	// octane adaptation: with a non-element child (e.g. text, or a compiled
+	// children-position render function), render children unchanged — the octane
+	// equivalent of upstream's warning path, without the warning.
+	if (!isValidElement(target)) {
+		return children;
+	}
+
+	let child: any = Children.only(target);
+
+	// octane is ref-as-prop (React 19 shape), so the child's own ref lives on its props.
+	let childRef = child.props?.ref;
+
+	// octane adaptation: memoize the composed ref so its identity is stable across
+	// renders (upstream rebuilds it every render; see the header note).
+	let mergedRef = useMemo(
+		() => mergeRefs(childRef, ref),
+		[childRef, ref],
+		subSlot(slot, 'mergedRef'),
+	);
+
+	return cloneElement(child, {
+		...mergeProps(focusableProps, child.props ?? {}),
+		ref: mergedRef,
+	});
+}

package/src/interactions/useHover.ts

@@ -0,0 +1,268 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/interactions/useHover.ts).
+// octane adaptations:
+// - `hoverProps` are octane NATIVE delegated event props (`onPointerEnter`/`onPointerLeave`
+//   receive native events; octane's enter/leave delegation is target-only, matching the
+//   platform). `DOMAttributes` from '@react-types/shared' becomes a local structural alias.
+// - `e.currentTarget` is EventTarget-typed on native events; casts to Element where
+//   upstream relied on React's element-typed currentTarget.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention; the
+//   explicit useMemo/useEffect dep arrays are preserved exactly.
+
+// Portions of the code in this file are based on code from react.
+// Original licensing for the following can be found in the
+// NOTICE file in the root directory of this source tree.
+// See https://github.com/facebook/react/tree/cc7c1aece46a6b69b41958d731e0fd27c94bfc6c/packages/react-interactions
+
+import type { HoverEvents } from '@react-types/shared';
+import { useEffect, useMemo, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { getEventTarget, nodeContains } from '../utils/shadowdom/DOMFunctions';
+import { getOwnerDocument } from '../utils/domHelpers';
+import { useGlobalListeners } from '../utils/useGlobalListeners';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React attribute types).
+export type DOMAttributes = Record<string, any>;
+
+export interface HoverProps extends HoverEvents {
+	/** Whether the hover events should be disabled. */
+	isDisabled?: boolean;
+}
+
+export interface HoverResult {
+	/** Props to spread on the target element. */
+	hoverProps: DOMAttributes;
+	isHovered: boolean;
+}
+
+// iOS fires onPointerEnter twice: once with pointerType="touch" and again with pointerType="mouse".
+// We want to ignore these emulated events so they do not trigger hover behavior.
+// See https://bugs.webkit.org/show_bug.cgi?id=214609.
+let globalIgnoreEmulatedMouseEvents = false;
+let hoverCount = 0;
+
+function setGlobalIgnoreEmulatedMouseEvents() {
+	globalIgnoreEmulatedMouseEvents = true;
+
+	// Clear globalIgnoreEmulatedMouseEvents after a short timeout. iOS fires onPointerEnter
+	// with pointerType="mouse" immediately after onPointerUp and before onFocus. On other
+	// devices that don't have this quirk, we don't want to ignore a mouse hover sometime in
+	// the distant future because a user previously touched the element.
+	setTimeout(() => {
+		globalIgnoreEmulatedMouseEvents = false;
+	}, 500);
+}
+
+function handleGlobalPointerEvent(e: PointerEvent) {
+	if (e.pointerType === 'touch') {
+		setGlobalIgnoreEmulatedMouseEvents();
+	}
+}
+
+function setupGlobalTouchEvents(): (() => void) | undefined {
+	let ownerDocument = getOwnerDocument(null);
+	if (typeof ownerDocument === 'undefined') {
+		return;
+	}
+
+	if (hoverCount === 0) {
+		if (typeof PointerEvent !== 'undefined') {
+			ownerDocument.addEventListener('pointerup', handleGlobalPointerEvent);
+		} else if (process.env.NODE_ENV === 'test') {
+			ownerDocument.addEventListener('touchend', setGlobalIgnoreEmulatedMouseEvents);
+		}
+	}
+
+	hoverCount++;
+	return () => {
+		hoverCount--;
+		if (hoverCount > 0) {
+			return;
+		}
+
+		if (typeof PointerEvent !== 'undefined') {
+			ownerDocument.removeEventListener('pointerup', handleGlobalPointerEvent);
+		} else if (process.env.NODE_ENV === 'test') {
+			ownerDocument.removeEventListener('touchend', setGlobalIgnoreEmulatedMouseEvents);
+		}
+	};
+}
+
+/**
+ * Handles pointer hover interactions for an element. Normalizes behavior
+ * across browsers and platforms, and ignores emulated mouse events on touch devices.
+ */
+export function useHover(props: HoverProps): HoverResult;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useHover(props: HoverProps, slot: symbol | undefined): HoverResult;
+export function useHover(...args: any[]): HoverResult {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useHover');
+	const props = user[0] as HoverProps;
+
+	let { onHoverStart, onHoverChange, onHoverEnd, isDisabled } = props;
+
+	let [isHovered, setHovered] = useState(false, subSlot(slot, 'hovered'));
+	let state = useRef(
+		{
+			isHovered: false,
+			ignoreEmulatedMouseEvents: false,
+			pointerType: '',
+			target: null as HTMLElement | null,
+		},
+		subSlot(slot, 'state'),
+	).current;
+
+	useEffect(setupGlobalTouchEvents, [], subSlot(slot, 'globalTouch'));
+	let { addGlobalListener, removeAllGlobalListeners } = useGlobalListeners(subSlot(slot, 'global'));
+
+	let { hoverProps, triggerHoverEnd } = useMemo(
+		() => {
+			let triggerHoverStart = (event: any, pointerType: any) => {
+				state.pointerType = pointerType;
+				if (
+					isDisabled ||
+					pointerType === 'touch' ||
+					state.isHovered ||
+					!nodeContains(event.currentTarget as Element, getEventTarget(event) as Element)
+				) {
+					return;
+				}
+
+				state.isHovered = true;
+				let target = event.currentTarget;
+				state.target = target;
+
+				// When an element that is hovered over is removed, no pointerleave event is fired by the browser,
+				// even though the originally hovered target may have shrunk in size so it is no longer hovered.
+				// However, a pointerover event will be fired on the new target the mouse is over.
+				// In Chrome this happens immediately. In Safari and Firefox, it happens upon moving the mouse one pixel.
+				addGlobalListener(
+					getOwnerDocument(getEventTarget(event) as Element),
+					'pointerover',
+					(e: PointerEvent) => {
+						if (
+							state.isHovered &&
+							state.target &&
+							!nodeContains(state.target, getEventTarget(e) as Element)
+						) {
+							triggerHoverEnd(e, e.pointerType);
+						}
+					},
+					{ capture: true },
+				);
+
+				if (onHoverStart) {
+					onHoverStart({
+						type: 'hoverstart',
+						target,
+						pointerType,
+					});
+				}
+
+				if (onHoverChange) {
+					onHoverChange(true);
+				}
+
+				setHovered(true);
+			};
+
+			let triggerHoverEnd = (event: any, pointerType: any) => {
+				let target = state.target;
+				state.pointerType = '';
+				state.target = null;
+
+				if (pointerType === 'touch' || !state.isHovered || !target) {
+					return;
+				}
+
+				state.isHovered = false;
+				removeAllGlobalListeners();
+
+				if (onHoverEnd) {
+					onHoverEnd({
+						type: 'hoverend',
+						target,
+						pointerType,
+					});
+				}
+
+				if (onHoverChange) {
+					onHoverChange(false);
+				}
+
+				setHovered(false);
+			};
+
+			let hoverProps: DOMAttributes = {};
+
+			if (typeof PointerEvent !== 'undefined') {
+				hoverProps.onPointerEnter = (e: PointerEvent) => {
+					if (globalIgnoreEmulatedMouseEvents && e.pointerType === 'mouse') {
+						return;
+					}
+
+					triggerHoverStart(e, e.pointerType);
+				};
+
+				hoverProps.onPointerLeave = (e: PointerEvent) => {
+					if (
+						!isDisabled &&
+						nodeContains(e.currentTarget as Element, getEventTarget(e) as Element)
+					) {
+						triggerHoverEnd(e, e.pointerType);
+					}
+				};
+			} else if (process.env.NODE_ENV === 'test') {
+				hoverProps.onTouchStart = () => {
+					state.ignoreEmulatedMouseEvents = true;
+				};
+
+				hoverProps.onMouseEnter = (e: MouseEvent) => {
+					if (!state.ignoreEmulatedMouseEvents && !globalIgnoreEmulatedMouseEvents) {
+						triggerHoverStart(e, 'mouse');
+					}
+
+					state.ignoreEmulatedMouseEvents = false;
+				};
+
+				hoverProps.onMouseLeave = (e: MouseEvent) => {
+					if (
+						!isDisabled &&
+						nodeContains(e.currentTarget as Element, getEventTarget(e) as Element)
+					) {
+						triggerHoverEnd(e, 'mouse');
+					}
+				};
+			}
+			return { hoverProps, triggerHoverEnd };
+		},
+		[
+			onHoverStart,
+			onHoverChange,
+			onHoverEnd,
+			isDisabled,
+			state,
+			addGlobalListener,
+			removeAllGlobalListeners,
+		],
+		subSlot(slot, 'props'),
+	);
+
+	useEffect(
+		() => {
+			// Call the triggerHoverEnd as soon as isDisabled changes to true
+			// Safe to call triggerHoverEnd, it will early return if we aren't currently hovering
+			if (isDisabled) {
+				triggerHoverEnd({ currentTarget: state.target }, state.pointerType);
+			}
+		},
+		[isDisabled],
+		subSlot(slot, 'disabled'),
+	);
+
+	return {
+		hoverProps,
+		isHovered,
+	};
+}

package/src/interactions/useInteractOutside.ts

@@ -0,0 +1,161 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/interactions/useInteractOutside.ts).
+// octane adaptations:
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention; the
+//   explicit `[ref, isDisabled]` effect deps are preserved exactly.
+// - Upstream's untyped handler/validator params are typed loosely (native events).
+
+// Portions of the code in this file are based on code from react.
+// Original licensing for the following can be found in the
+// NOTICE file in the root directory of this source tree.
+// See https://github.com/facebook/react/tree/cc7c1aece46a6b69b41958d731e0fd27c94bfc6c/packages/react-interactions
+
+import type { RefObject } from '@react-types/shared';
+import { useEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { getEventTarget, nodeContains } from '../utils/shadowdom/DOMFunctions';
+import { getOwnerDocument } from '../utils/domHelpers';
+import { useEffectEvent } from '../utils/useEffectEvent';
+
+export interface InteractOutsideProps {
+	ref: RefObject<Element | null>;
+	onInteractOutside?: (e: PointerEvent) => void;
+	onInteractOutsideStart?: (e: PointerEvent) => void;
+	/** Whether the interact outside events should be disabled. */
+	isDisabled?: boolean;
+}
+
+/**
+ * Example, used in components like Dialogs and Popovers so they can close
+ * when a user clicks outside them.
+ */
+export function useInteractOutside(props: InteractOutsideProps): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useInteractOutside(props: InteractOutsideProps, slot: symbol | undefined): void;
+export function useInteractOutside(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useInteractOutside');
+	const props = user[0] as InteractOutsideProps;
+
+	let { ref, onInteractOutside, isDisabled, onInteractOutsideStart } = props;
+	let stateRef = useRef(
+		{
+			isPointerDown: false,
+			ignoreEmulatedMouseEvents: false,
+		},
+		subSlot(slot, 'state'),
+	);
+
+	let onPointerDown = useEffectEvent(
+		(e: any) => {
+			if (onInteractOutside && isValidEvent(e, ref)) {
+				if (onInteractOutsideStart) {
+					onInteractOutsideStart(e);
+				}
+				stateRef.current.isPointerDown = true;
+			}
+		},
+		subSlot(slot, 'pointerDown'),
+	);
+
+	let triggerInteractOutside = useEffectEvent(
+		(e: PointerEvent) => {
+			if (onInteractOutside) {
+				onInteractOutside(e);
+			}
+		},
+		subSlot(slot, 'trigger'),
+	);
+
+	useEffect(
+		() => {
+			let state = stateRef.current;
+			if (isDisabled) {
+				return;
+			}
+
+			const element = ref.current;
+			const documentObject = getOwnerDocument(element);
+
+			// Use pointer events if available. Otherwise, fall back to mouse and touch events.
+			if (typeof PointerEvent !== 'undefined') {
+				let onClick = (e: any) => {
+					if (state.isPointerDown && isValidEvent(e, ref)) {
+						triggerInteractOutside(e);
+					}
+					state.isPointerDown = false;
+				};
+
+				// changing these to capture phase fixed combobox
+				// Use click instead of pointerup to avoid Android Chrome issue
+				// https://issues.chromium.org/issues/40732224
+				documentObject.addEventListener('pointerdown', onPointerDown, true);
+				documentObject.addEventListener('click', onClick, true);
+
+				return () => {
+					documentObject.removeEventListener('pointerdown', onPointerDown, true);
+					documentObject.removeEventListener('click', onClick, true);
+				};
+			} else if (process.env.NODE_ENV === 'test') {
+				let onMouseUp = (e: any) => {
+					if (state.ignoreEmulatedMouseEvents) {
+						state.ignoreEmulatedMouseEvents = false;
+					} else if (state.isPointerDown && isValidEvent(e, ref)) {
+						triggerInteractOutside(e);
+					}
+					state.isPointerDown = false;
+				};
+
+				let onTouchEnd = (e: any) => {
+					state.ignoreEmulatedMouseEvents = true;
+					if (state.isPointerDown && isValidEvent(e, ref)) {
+						triggerInteractOutside(e);
+					}
+					state.isPointerDown = false;
+				};
+
+				documentObject.addEventListener('mousedown', onPointerDown, true);
+				documentObject.addEventListener('mouseup', onMouseUp, true);
+				documentObject.addEventListener('touchstart', onPointerDown, true);
+				documentObject.addEventListener('touchend', onTouchEnd, true);
+
+				return () => {
+					documentObject.removeEventListener('mousedown', onPointerDown, true);
+					documentObject.removeEventListener('mouseup', onMouseUp, true);
+					documentObject.removeEventListener('touchstart', onPointerDown, true);
+					documentObject.removeEventListener('touchend', onTouchEnd, true);
+				};
+			}
+		},
+		[ref, isDisabled],
+		subSlot(slot, 'listen'),
+	);
+}
+
+function isValidEvent(event: any, ref: RefObject<Element | null>): boolean {
+	if (event.button > 0) {
+		return false;
+	}
+	let target = getEventTarget(event) as Element;
+	if (target) {
+		// if the event target is no longer in the document, ignore
+		const ownerDocument = target.ownerDocument;
+		if (!ownerDocument || !nodeContains(ownerDocument.documentElement, target)) {
+			return false;
+		}
+		// If the target is within a top layer element (e.g. toasts), ignore.
+		if (target.closest('[data-react-aria-top-layer]')) {
+			return false;
+		}
+	}
+
+	if (!ref.current) {
+		return false;
+	}
+
+	// When the event source is inside a Shadow DOM, event.target is just the shadow root.
+	// Using event.composedPath instead means we can get the actual element inside the shadow root.
+	// This only works if the shadow root is open, there is no way to detect if it is closed.
+	// If the event composed path contains the ref, interaction is inside.
+	return !event.composedPath().includes(ref.current);
+}

package/src/interactions/useKeyboard.ts

@@ -0,0 +1,50 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/interactions/useKeyboard.ts).
+// octane adaptations:
+// - `KeyboardEvents` / `DOMAttributes` from '@react-types/shared' are typed over React's
+//   synthetic events; local structural aliases over native KeyboardEvent replace them.
+// - Public-hook slot threading (splitSlot) per the binding convention; no octane base hooks
+//   are composed here, so the slot is absorbed and unused.
+import type { BaseEvent } from './createEventHandler';
+import { createEventHandler } from './createEventHandler';
+import { splitSlot } from '../internal';
+
+// octane adaptation: native-event handler props (upstream: KeyboardEvents from '@react-types/shared').
+export interface KeyboardEvents {
+	/** Handler that is called when a key is pressed. */
+	onKeyDown?: (e: BaseEvent<KeyboardEvent>) => void;
+	/** Handler that is called when a key is released. */
+	onKeyUp?: (e: BaseEvent<KeyboardEvent>) => void;
+}
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React attribute types).
+export type DOMAttributes = Record<string, any>;
+
+export interface KeyboardProps extends KeyboardEvents {
+	/** Whether the keyboard events should be disabled. */
+	isDisabled?: boolean;
+}
+
+export interface KeyboardResult {
+	/** Props to spread onto the target element. */
+	keyboardProps: DOMAttributes;
+}
+
+/**
+ * Handles keyboard interactions for a focusable element.
+ */
+export function useKeyboard(props: KeyboardProps): KeyboardResult;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useKeyboard(props: KeyboardProps, slot: symbol | undefined): KeyboardResult;
+export function useKeyboard(...args: any[]): KeyboardResult {
+	const [user] = splitSlot(args);
+	const props = user[0] as KeyboardProps;
+
+	return {
+		keyboardProps: props.isDisabled
+			? {}
+			: {
+					onKeyDown: createEventHandler(props.onKeyDown),
+					onKeyUp: createEventHandler(props.onKeyUp),
+				},
+	};
+}