@puzzle-ui/hooks 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @puzzle-ui/hooks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React hooks for keyboard events and roving focus, shared by Puzzle UI
+components and available for custom interfaces.
+
+> Puzzle is under active development. APIs may change without notice; use it
+> for experimentation and evaluation rather than production applications.
+
+## Installation
+
+```sh
+npm install @puzzle-ui/hooks
+# or
+bun add @puzzle-ui/hooks
+# or
+pnpm add @puzzle-ui/hooks
+# or
+yarn add @puzzle-ui/hooks
+```
+
+Requires React 19 (`^19.0.0`). No theme provider or stylesheet is required.
+
+## Keyboard events
+
+`useKeyboardKeys` subscribes to window keyboard events and cleans up its
+listeners when disabled or unmounted.
+
+```tsx
+"use client";
+
+import { useKeyboardKeys } from "@puzzle-ui/hooks";
+
+export const EscapeHint = () => {
+  useKeyboardKeys({
+    keys: ["Escape"],
+    onKeyDown: () => console.log("Escape pressed"),
+  });
+
+  return <p>Press Escape to try the keyboard handler.</p>;
+};
+```
+
+Options include `keys`, `onKeyDown`, `onKeyUp`, `enabled`, `preventDefault`,
+and `stopPropagation`. Callbacks receive modifier flags, repeat state, and
+the native event. These are global listeners: scope application shortcuts
+carefully so they do not interfere with inputs or other controls.
+
+## Roving focus
+
+`useRovingFocus<T>` manages a single tab stop among items identified by stable
+IDs. It supports horizontal, vertical, or both orientations, RTL direction,
+looping, disabled items, and an initial active ID.
+
+Wire its `getItemRef`, `getItemTabIndex`, `onItemFocus`, and `onItemKeyDown`
+helpers to each focusable element. Use `focusItem` for programmatic focus
+and `activeId` to inspect the current item.
+
+Focus management does not supply widget semantics or selection state. Add
+the appropriate roles, accessible names, and selection behavior yourself.
+
+## Compatibility
+
+Call these hooks in React function components or custom hooks, not in server
+components. In React Server Component applications, use a `"use client"`
+module for interactive consumers. ESM and CommonJS builds and their
+TypeScript declarations are included.
+
+## Development
+
+From an installed repository checkout:
+
+```sh
+npm run build --workspace=@puzzle-ui/hooks
+```
+
+This package currently has no dedicated test script. `prepack` rebuilds it
+before packing or publishing. See the root
+[publishing guide](../../README.md#publishing-packages).
+
+## License
+
+MIT. See [LICENSE](../../LICENSE); the published license is at `dist/LICENSE`.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sjoerd van Den Berg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_use_keyboard_keys = require("./use-keyboard-keys.cjs");
+const require_use_roving_focus = require("./use-roving-focus.cjs");
+exports.useKeyboardKeys = require_use_keyboard_keys.useKeyboardKeys;
+exports.useRovingFocus = require_use_roving_focus.useRovingFocus;

package/dist/index.d.cts

@@ -0,0 +1,3 @@
+import { UseKeyboardKeysEvent, UseKeyboardKeysOptions, useKeyboardKeys } from "./use-keyboard-keys.cjs";
+import { RovingFocusItem, RovingFocusOrientation, UseRovingFocusOptions, UseRovingFocusReturn, useRovingFocus } from "./use-roving-focus.cjs";
+export { type RovingFocusItem, type RovingFocusOrientation, type UseKeyboardKeysEvent, type UseKeyboardKeysOptions, type UseRovingFocusOptions, type UseRovingFocusReturn, useKeyboardKeys, useRovingFocus };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { UseKeyboardKeysEvent, UseKeyboardKeysOptions, useKeyboardKeys } from "./use-keyboard-keys.js";
+import { RovingFocusItem, RovingFocusOrientation, UseRovingFocusOptions, UseRovingFocusReturn, useRovingFocus } from "./use-roving-focus.js";
+export { type RovingFocusItem, type RovingFocusOrientation, type UseKeyboardKeysEvent, type UseKeyboardKeysOptions, type UseRovingFocusOptions, type UseRovingFocusReturn, useKeyboardKeys, useRovingFocus };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { useKeyboardKeys } from "./use-keyboard-keys.js";
+import { useRovingFocus } from "./use-roving-focus.js";
+export { useKeyboardKeys, useRovingFocus };

package/dist/use-keyboard-keys.cjs

@@ -0,0 +1,89 @@
+let react = require("react");
+// src/use-keyboard-keys.ts
+function normalizeKey(key) {
+	const normalized = key.toLowerCase();
+	if (normalized === "space" || normalized === "spacebar") return " ";
+	return normalized;
+}
+function useKeyboardKeys({ keys, onKeyDown, onKeyUp, preventDefault = false, stopPropagation = false, enabled = true }) {
+	const pressedKeys = (0, react.useRef)(/* @__PURE__ */ new Set());
+	const callbacksRef = (0, react.useRef)({
+		onKeyDown,
+		onKeyUp
+	});
+	(0, react.useEffect)(() => {
+		callbacksRef.current = {
+			onKeyDown,
+			onKeyUp
+		};
+	}, [onKeyDown, onKeyUp]);
+	const keysSignature = JSON.stringify([...new Set(keys.map(normalizeKey))].sort());
+	const hasCallback = Boolean(onKeyDown || onKeyUp);
+	(0, react.useEffect)(() => {
+		if (!enabled || !hasCallback) {
+			pressedKeys.current.clear();
+			return;
+		}
+		const subscribedKeys = new Set(JSON.parse(keysSignature));
+		if (subscribedKeys.size === 0) {
+			pressedKeys.current.clear();
+			return;
+		}
+		const getModifierState = (modifier, nativeState, normalizedKey, type) => {
+			if (normalizedKey === modifier) return type === "keydown";
+			return nativeState || pressedKeys.current.has(modifier);
+		};
+		const handleKeyboardEvent = (event, type) => {
+			const normalizedKey = normalizeKey(event.key);
+			if (type === "keydown") pressedKeys.current.add(normalizedKey);
+			else pressedKeys.current.delete(normalizedKey);
+			if (!subscribedKeys.has(normalizedKey)) return;
+			const callback = type === "keydown" ? callbacksRef.current.onKeyDown : callbacksRef.current.onKeyUp;
+			if (!callback) return;
+			if (preventDefault && event.cancelable) event.preventDefault();
+			if (stopPropagation) event.stopPropagation();
+			callback({
+				key: event.key,
+				type,
+				shiftKey: getModifierState("shift", event.shiftKey, normalizedKey, type),
+				ctrlKey: getModifierState("control", event.ctrlKey, normalizedKey, type),
+				metaKey: getModifierState("meta", event.metaKey, normalizedKey, type),
+				altKey: getModifierState("alt", event.altKey, normalizedKey, type),
+				repeat: event.repeat,
+				nativeEvent: event
+			});
+		};
+		const handleKeyDown = (event) => {
+			handleKeyboardEvent(event, "keydown");
+		};
+		const handleKeyUp = (event) => {
+			handleKeyboardEvent(event, "keyup");
+		};
+		const clearPressedKeys = () => {
+			pressedKeys.current.clear();
+		};
+		const handleVisibilityChange = () => {
+			if (document.visibilityState === "hidden") clearPressedKeys();
+		};
+		window.addEventListener("keydown", handleKeyDown, true);
+		window.addEventListener("keyup", handleKeyUp, true);
+		window.addEventListener("blur", clearPressedKeys);
+		document.addEventListener("visibilitychange", handleVisibilityChange);
+		return () => {
+			window.removeEventListener("keydown", handleKeyDown, true);
+			window.removeEventListener("keyup", handleKeyUp, true);
+			window.removeEventListener("blur", clearPressedKeys);
+			document.removeEventListener("visibilitychange", handleVisibilityChange);
+			clearPressedKeys();
+		};
+	}, [
+		enabled,
+		hasCallback,
+		keysSignature,
+		preventDefault,
+		stopPropagation
+	]);
+}
+exports.useKeyboardKeys = useKeyboardKeys;
+
+//# sourceMappingURL=use-keyboard-keys.cjs.map

package/dist/use-keyboard-keys.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-keyboard-keys.cjs","names":["useRef"],"sources":["../src/use-keyboard-keys.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\nexport type KeyboardEventType = \"keydown\" | \"keyup\";\n\nexport interface UseKeyboardKeysEvent {\n  key: string;\n  type: KeyboardEventType;\n  shiftKey: boolean;\n  ctrlKey: boolean;\n  metaKey: boolean;\n  altKey: boolean;\n  repeat: boolean;\n  nativeEvent: KeyboardEvent;\n}\n\nexport interface UseKeyboardKeysOptions {\n  keys: readonly string[];\n  onKeyDown?: (event: UseKeyboardKeysEvent) => void;\n  onKeyUp?: (event: UseKeyboardKeysEvent) => void;\n  preventDefault?: boolean;\n  stopPropagation?: boolean;\n  enabled?: boolean;\n}\n\nfunction normalizeKey(key: string): string {\n  const normalized = key.toLowerCase();\n\n  if (normalized === \"space\" || normalized === \"spacebar\") {\n    return \" \";\n  }\n\n  return normalized;\n}\n\ntype ModifierKey = \"shift\" | \"control\" | \"meta\" | \"alt\";\n\nexport function useKeyboardKeys({\n  keys,\n  onKeyDown,\n  onKeyUp,\n  preventDefault = false,\n  stopPropagation = false,\n  enabled = true,\n}: UseKeyboardKeysOptions): void {\n  const pressedKeys = useRef(new Set<string>());\n  const callbacksRef = useRef({ onKeyDown, onKeyUp });\n\n  useEffect(() => {\n    callbacksRef.current = { onKeyDown, onKeyUp };\n  }, [onKeyDown, onKeyUp]);\n\n  const keysSignature = JSON.stringify(\n    [...new Set(keys.map(normalizeKey))].sort(),\n  );\n\n  const hasCallback = Boolean(onKeyDown || onKeyUp);\n\n  useEffect(() => {\n    if (!enabled || !hasCallback) {\n      pressedKeys.current.clear();\n      return;\n    }\n\n    const subscribedKeys = new Set<string>(\n      JSON.parse(keysSignature) as string[],\n    );\n\n    if (subscribedKeys.size === 0) {\n      pressedKeys.current.clear();\n      return;\n    }\n\n    const getModifierState = (\n      modifier: ModifierKey,\n      nativeState: boolean,\n      normalizedKey: string,\n      type: KeyboardEventType,\n    ): boolean => {\n      if (normalizedKey === modifier) {\n        return type === \"keydown\";\n      }\n\n      return nativeState || pressedKeys.current.has(modifier);\n    };\n\n    const handleKeyboardEvent = (\n      event: KeyboardEvent,\n      type: KeyboardEventType,\n    ) => {\n      const normalizedKey = normalizeKey(event.key);\n\n      if (type === \"keydown\") {\n        pressedKeys.current.add(normalizedKey);\n      } else {\n        pressedKeys.current.delete(normalizedKey);\n      }\n\n      if (!subscribedKeys.has(normalizedKey)) {\n        return;\n      }\n\n      const callback =\n        type === \"keydown\"\n          ? callbacksRef.current.onKeyDown\n          : callbacksRef.current.onKeyUp;\n\n      if (!callback) {\n        return;\n      }\n\n      if (preventDefault && event.cancelable) {\n        event.preventDefault();\n      }\n\n      if (stopPropagation) {\n        event.stopPropagation();\n      }\n\n      callback({\n        key: event.key,\n        type,\n        shiftKey: getModifierState(\n          \"shift\",\n          event.shiftKey,\n          normalizedKey,\n          type,\n        ),\n        ctrlKey: getModifierState(\n          \"control\",\n          event.ctrlKey,\n          normalizedKey,\n          type,\n        ),\n        metaKey: getModifierState(\"meta\", event.metaKey, normalizedKey, type),\n        altKey: getModifierState(\"alt\", event.altKey, normalizedKey, type),\n        repeat: event.repeat,\n        nativeEvent: event,\n      });\n    };\n\n    const handleKeyDown = (event: KeyboardEvent) => {\n      handleKeyboardEvent(event, \"keydown\");\n    };\n\n    const handleKeyUp = (event: KeyboardEvent) => {\n      handleKeyboardEvent(event, \"keyup\");\n    };\n\n    const clearPressedKeys = () => {\n      pressedKeys.current.clear();\n    };\n\n    const handleVisibilityChange = () => {\n      if (document.visibilityState === \"hidden\") {\n        clearPressedKeys();\n      }\n    };\n\n    window.addEventListener(\"keydown\", handleKeyDown, true);\n    window.addEventListener(\"keyup\", handleKeyUp, true);\n    window.addEventListener(\"blur\", clearPressedKeys);\n    document.addEventListener(\"visibilitychange\", handleVisibilityChange);\n\n    return () => {\n      window.removeEventListener(\"keydown\", handleKeyDown, true);\n      window.removeEventListener(\"keyup\", handleKeyUp, true);\n      window.removeEventListener(\"blur\", clearPressedKeys);\n      document.removeEventListener(\"visibilitychange\", handleVisibilityChange);\n\n      clearPressedKeys();\n    };\n  }, [enabled, hasCallback, keysSignature, preventDefault, stopPropagation]);\n}\n"],"mappings":";;AAwBA,SAAS,aAAa,KAAqB;CACzC,MAAM,aAAa,IAAI,YAAY;CAEnC,IAAI,eAAe,WAAW,eAAe,YAC3C,OAAO;CAGT,OAAO;AACT;AAIA,SAAgB,gBAAgB,EAC9B,MACA,WACA,SACA,iBAAiB,OACjB,kBAAkB,OAClB,UAAU,QACqB;CAC/B,MAAM,eAAA,GAAcA,MAAAA,OAAAA,iBAAO,IAAI,IAAY,CAAC;CAC5C,MAAM,gBAAA,GAAeA,MAAAA,OAAAA,CAAO;EAAE;EAAW;CAAQ,CAAC;CAElD,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,aAAa,UAAU;GAAE;GAAW;EAAQ;CAC9C,GAAG,CAAC,WAAW,OAAO,CAAC;CAEvB,MAAM,gBAAgB,KAAK,UACzB,CAAC,GAAG,IAAI,IAAI,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK,CAC5C;CAEA,MAAM,cAAc,QAAQ,aAAa,OAAO;CAEhD,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,IAAI,CAAC,WAAW,CAAC,aAAa;GAC5B,YAAY,QAAQ,MAAM;GAC1B;EACF;EAEA,MAAM,iBAAiB,IAAI,IACzB,KAAK,MAAM,aAAa,CAC1B;EAEA,IAAI,eAAe,SAAS,GAAG;GAC7B,YAAY,QAAQ,MAAM;GAC1B;EACF;EAEA,MAAM,oBACJ,UACA,aACA,eACA,SACY;GACZ,IAAI,kBAAkB,UACpB,OAAO,SAAS;GAGlB,OAAO,eAAe,YAAY,QAAQ,IAAI,QAAQ;EACxD;EAEA,MAAM,uBACJ,OACA,SACG;GACH,MAAM,gBAAgB,aAAa,MAAM,GAAG;GAE5C,IAAI,SAAS,WACX,YAAY,QAAQ,IAAI,aAAa;QAErC,YAAY,QAAQ,OAAO,aAAa;GAG1C,IAAI,CAAC,eAAe,IAAI,aAAa,GACnC;GAGF,MAAM,WACJ,SAAS,YACL,aAAa,QAAQ,YACrB,aAAa,QAAQ;GAE3B,IAAI,CAAC,UACH;GAGF,IAAI,kBAAkB,MAAM,YAC1B,MAAM,eAAe;GAGvB,IAAI,iBACF,MAAM,gBAAgB;GAGxB,SAAS;IACP,KAAK,MAAM;IACX;IACA,UAAU,iBACR,SACA,MAAM,UACN,eACA,IACF;IACA,SAAS,iBACP,WACA,MAAM,SACN,eACA,IACF;IACA,SAAS,iBAAiB,QAAQ,MAAM,SAAS,eAAe,IAAI;IACpE,QAAQ,iBAAiB,OAAO,MAAM,QAAQ,eAAe,IAAI;IACjE,QAAQ,MAAM;IACd,aAAa;GACf,CAAC;EACH;EAEA,MAAM,iBAAiB,UAAyB;GAC9C,oBAAoB,OAAO,SAAS;EACtC;EAEA,MAAM,eAAe,UAAyB;GAC5C,oBAAoB,OAAO,OAAO;EACpC;EAEA,MAAM,yBAAyB;GAC7B,YAAY,QAAQ,MAAM;EAC5B;EAEA,MAAM,+BAA+B;GACnC,IAAI,SAAS,oBAAoB,UAC/B,iBAAiB;EAErB;EAEA,OAAO,iBAAiB,WAAW,eAAe,IAAI;EACtD,OAAO,iBAAiB,SAAS,aAAa,IAAI;EAClD,OAAO,iBAAiB,QAAQ,gBAAgB;EAChD,SAAS,iBAAiB,oBAAoB,sBAAsB;EAEpE,aAAa;GACX,OAAO,oBAAoB,WAAW,eAAe,IAAI;GACzD,OAAO,oBAAoB,SAAS,aAAa,IAAI;GACrD,OAAO,oBAAoB,QAAQ,gBAAgB;GACnD,SAAS,oBAAoB,oBAAoB,sBAAsB;GAEvE,iBAAiB;EACnB;CACF,GAAG;EAAC;EAAS;EAAa;EAAe;EAAgB;CAAe,CAAC;AAC3E"}

package/dist/use-keyboard-keys.d.cts

@@ -0,0 +1,20 @@
+export type KeyboardEventType = "keydown" | "keyup";
+export interface UseKeyboardKeysEvent {
+  key: string;
+  type: KeyboardEventType;
+  shiftKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  altKey: boolean;
+  repeat: boolean;
+  nativeEvent: KeyboardEvent;
+}
+export interface UseKeyboardKeysOptions {
+  keys: readonly string[];
+  onKeyDown?: (event: UseKeyboardKeysEvent) => void;
+  onKeyUp?: (event: UseKeyboardKeysEvent) => void;
+  preventDefault?: boolean;
+  stopPropagation?: boolean;
+  enabled?: boolean;
+}
+export declare function useKeyboardKeys({ keys, onKeyDown, onKeyUp, preventDefault, stopPropagation, enabled }: UseKeyboardKeysOptions): void;

package/dist/use-keyboard-keys.d.ts

@@ -0,0 +1,20 @@
+export type KeyboardEventType = "keydown" | "keyup";
+export interface UseKeyboardKeysEvent {
+  key: string;
+  type: KeyboardEventType;
+  shiftKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  altKey: boolean;
+  repeat: boolean;
+  nativeEvent: KeyboardEvent;
+}
+export interface UseKeyboardKeysOptions {
+  keys: readonly string[];
+  onKeyDown?: (event: UseKeyboardKeysEvent) => void;
+  onKeyUp?: (event: UseKeyboardKeysEvent) => void;
+  preventDefault?: boolean;
+  stopPropagation?: boolean;
+  enabled?: boolean;
+}
+export declare function useKeyboardKeys({ keys, onKeyDown, onKeyUp, preventDefault, stopPropagation, enabled }: UseKeyboardKeysOptions): void;

package/dist/use-keyboard-keys.js

@@ -0,0 +1,89 @@
+import { useEffect, useRef } from "react";
+// src/use-keyboard-keys.ts
+function normalizeKey(key) {
+	const normalized = key.toLowerCase();
+	if (normalized === "space" || normalized === "spacebar") return " ";
+	return normalized;
+}
+function useKeyboardKeys({ keys, onKeyDown, onKeyUp, preventDefault = false, stopPropagation = false, enabled = true }) {
+	const pressedKeys = useRef(/* @__PURE__ */ new Set());
+	const callbacksRef = useRef({
+		onKeyDown,
+		onKeyUp
+	});
+	useEffect(() => {
+		callbacksRef.current = {
+			onKeyDown,
+			onKeyUp
+		};
+	}, [onKeyDown, onKeyUp]);
+	const keysSignature = JSON.stringify([...new Set(keys.map(normalizeKey))].sort());
+	const hasCallback = Boolean(onKeyDown || onKeyUp);
+	useEffect(() => {
+		if (!enabled || !hasCallback) {
+			pressedKeys.current.clear();
+			return;
+		}
+		const subscribedKeys = new Set(JSON.parse(keysSignature));
+		if (subscribedKeys.size === 0) {
+			pressedKeys.current.clear();
+			return;
+		}
+		const getModifierState = (modifier, nativeState, normalizedKey, type) => {
+			if (normalizedKey === modifier) return type === "keydown";
+			return nativeState || pressedKeys.current.has(modifier);
+		};
+		const handleKeyboardEvent = (event, type) => {
+			const normalizedKey = normalizeKey(event.key);
+			if (type === "keydown") pressedKeys.current.add(normalizedKey);
+			else pressedKeys.current.delete(normalizedKey);
+			if (!subscribedKeys.has(normalizedKey)) return;
+			const callback = type === "keydown" ? callbacksRef.current.onKeyDown : callbacksRef.current.onKeyUp;
+			if (!callback) return;
+			if (preventDefault && event.cancelable) event.preventDefault();
+			if (stopPropagation) event.stopPropagation();
+			callback({
+				key: event.key,
+				type,
+				shiftKey: getModifierState("shift", event.shiftKey, normalizedKey, type),
+				ctrlKey: getModifierState("control", event.ctrlKey, normalizedKey, type),
+				metaKey: getModifierState("meta", event.metaKey, normalizedKey, type),
+				altKey: getModifierState("alt", event.altKey, normalizedKey, type),
+				repeat: event.repeat,
+				nativeEvent: event
+			});
+		};
+		const handleKeyDown = (event) => {
+			handleKeyboardEvent(event, "keydown");
+		};
+		const handleKeyUp = (event) => {
+			handleKeyboardEvent(event, "keyup");
+		};
+		const clearPressedKeys = () => {
+			pressedKeys.current.clear();
+		};
+		const handleVisibilityChange = () => {
+			if (document.visibilityState === "hidden") clearPressedKeys();
+		};
+		window.addEventListener("keydown", handleKeyDown, true);
+		window.addEventListener("keyup", handleKeyUp, true);
+		window.addEventListener("blur", clearPressedKeys);
+		document.addEventListener("visibilitychange", handleVisibilityChange);
+		return () => {
+			window.removeEventListener("keydown", handleKeyDown, true);
+			window.removeEventListener("keyup", handleKeyUp, true);
+			window.removeEventListener("blur", clearPressedKeys);
+			document.removeEventListener("visibilitychange", handleVisibilityChange);
+			clearPressedKeys();
+		};
+	}, [
+		enabled,
+		hasCallback,
+		keysSignature,
+		preventDefault,
+		stopPropagation
+	]);
+}
+export { useKeyboardKeys };
+
+//# sourceMappingURL=use-keyboard-keys.js.map

package/dist/use-keyboard-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-keyboard-keys.js","names":[],"sources":["../src/use-keyboard-keys.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\nexport type KeyboardEventType = \"keydown\" | \"keyup\";\n\nexport interface UseKeyboardKeysEvent {\n  key: string;\n  type: KeyboardEventType;\n  shiftKey: boolean;\n  ctrlKey: boolean;\n  metaKey: boolean;\n  altKey: boolean;\n  repeat: boolean;\n  nativeEvent: KeyboardEvent;\n}\n\nexport interface UseKeyboardKeysOptions {\n  keys: readonly string[];\n  onKeyDown?: (event: UseKeyboardKeysEvent) => void;\n  onKeyUp?: (event: UseKeyboardKeysEvent) => void;\n  preventDefault?: boolean;\n  stopPropagation?: boolean;\n  enabled?: boolean;\n}\n\nfunction normalizeKey(key: string): string {\n  const normalized = key.toLowerCase();\n\n  if (normalized === \"space\" || normalized === \"spacebar\") {\n    return \" \";\n  }\n\n  return normalized;\n}\n\ntype ModifierKey = \"shift\" | \"control\" | \"meta\" | \"alt\";\n\nexport function useKeyboardKeys({\n  keys,\n  onKeyDown,\n  onKeyUp,\n  preventDefault = false,\n  stopPropagation = false,\n  enabled = true,\n}: UseKeyboardKeysOptions): void {\n  const pressedKeys = useRef(new Set<string>());\n  const callbacksRef = useRef({ onKeyDown, onKeyUp });\n\n  useEffect(() => {\n    callbacksRef.current = { onKeyDown, onKeyUp };\n  }, [onKeyDown, onKeyUp]);\n\n  const keysSignature = JSON.stringify(\n    [...new Set(keys.map(normalizeKey))].sort(),\n  );\n\n  const hasCallback = Boolean(onKeyDown || onKeyUp);\n\n  useEffect(() => {\n    if (!enabled || !hasCallback) {\n      pressedKeys.current.clear();\n      return;\n    }\n\n    const subscribedKeys = new Set<string>(\n      JSON.parse(keysSignature) as string[],\n    );\n\n    if (subscribedKeys.size === 0) {\n      pressedKeys.current.clear();\n      return;\n    }\n\n    const getModifierState = (\n      modifier: ModifierKey,\n      nativeState: boolean,\n      normalizedKey: string,\n      type: KeyboardEventType,\n    ): boolean => {\n      if (normalizedKey === modifier) {\n        return type === \"keydown\";\n      }\n\n      return nativeState || pressedKeys.current.has(modifier);\n    };\n\n    const handleKeyboardEvent = (\n      event: KeyboardEvent,\n      type: KeyboardEventType,\n    ) => {\n      const normalizedKey = normalizeKey(event.key);\n\n      if (type === \"keydown\") {\n        pressedKeys.current.add(normalizedKey);\n      } else {\n        pressedKeys.current.delete(normalizedKey);\n      }\n\n      if (!subscribedKeys.has(normalizedKey)) {\n        return;\n      }\n\n      const callback =\n        type === \"keydown\"\n          ? callbacksRef.current.onKeyDown\n          : callbacksRef.current.onKeyUp;\n\n      if (!callback) {\n        return;\n      }\n\n      if (preventDefault && event.cancelable) {\n        event.preventDefault();\n      }\n\n      if (stopPropagation) {\n        event.stopPropagation();\n      }\n\n      callback({\n        key: event.key,\n        type,\n        shiftKey: getModifierState(\n          \"shift\",\n          event.shiftKey,\n          normalizedKey,\n          type,\n        ),\n        ctrlKey: getModifierState(\n          \"control\",\n          event.ctrlKey,\n          normalizedKey,\n          type,\n        ),\n        metaKey: getModifierState(\"meta\", event.metaKey, normalizedKey, type),\n        altKey: getModifierState(\"alt\", event.altKey, normalizedKey, type),\n        repeat: event.repeat,\n        nativeEvent: event,\n      });\n    };\n\n    const handleKeyDown = (event: KeyboardEvent) => {\n      handleKeyboardEvent(event, \"keydown\");\n    };\n\n    const handleKeyUp = (event: KeyboardEvent) => {\n      handleKeyboardEvent(event, \"keyup\");\n    };\n\n    const clearPressedKeys = () => {\n      pressedKeys.current.clear();\n    };\n\n    const handleVisibilityChange = () => {\n      if (document.visibilityState === \"hidden\") {\n        clearPressedKeys();\n      }\n    };\n\n    window.addEventListener(\"keydown\", handleKeyDown, true);\n    window.addEventListener(\"keyup\", handleKeyUp, true);\n    window.addEventListener(\"blur\", clearPressedKeys);\n    document.addEventListener(\"visibilitychange\", handleVisibilityChange);\n\n    return () => {\n      window.removeEventListener(\"keydown\", handleKeyDown, true);\n      window.removeEventListener(\"keyup\", handleKeyUp, true);\n      window.removeEventListener(\"blur\", clearPressedKeys);\n      document.removeEventListener(\"visibilitychange\", handleVisibilityChange);\n\n      clearPressedKeys();\n    };\n  }, [enabled, hasCallback, keysSignature, preventDefault, stopPropagation]);\n}\n"],"mappings":";;AAwBA,SAAS,aAAa,KAAqB;CACzC,MAAM,aAAa,IAAI,YAAY;CAEnC,IAAI,eAAe,WAAW,eAAe,YAC3C,OAAO;CAGT,OAAO;AACT;AAIA,SAAgB,gBAAgB,EAC9B,MACA,WACA,SACA,iBAAiB,OACjB,kBAAkB,OAClB,UAAU,QACqB;CAC/B,MAAM,cAAc,uBAAO,IAAI,IAAY,CAAC;CAC5C,MAAM,eAAe,OAAO;EAAE;EAAW;CAAQ,CAAC;CAElD,gBAAgB;EACd,aAAa,UAAU;GAAE;GAAW;EAAQ;CAC9C,GAAG,CAAC,WAAW,OAAO,CAAC;CAEvB,MAAM,gBAAgB,KAAK,UACzB,CAAC,GAAG,IAAI,IAAI,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK,CAC5C;CAEA,MAAM,cAAc,QAAQ,aAAa,OAAO;CAEhD,gBAAgB;EACd,IAAI,CAAC,WAAW,CAAC,aAAa;GAC5B,YAAY,QAAQ,MAAM;GAC1B;EACF;EAEA,MAAM,iBAAiB,IAAI,IACzB,KAAK,MAAM,aAAa,CAC1B;EAEA,IAAI,eAAe,SAAS,GAAG;GAC7B,YAAY,QAAQ,MAAM;GAC1B;EACF;EAEA,MAAM,oBACJ,UACA,aACA,eACA,SACY;GACZ,IAAI,kBAAkB,UACpB,OAAO,SAAS;GAGlB,OAAO,eAAe,YAAY,QAAQ,IAAI,QAAQ;EACxD;EAEA,MAAM,uBACJ,OACA,SACG;GACH,MAAM,gBAAgB,aAAa,MAAM,GAAG;GAE5C,IAAI,SAAS,WACX,YAAY,QAAQ,IAAI,aAAa;QAErC,YAAY,QAAQ,OAAO,aAAa;GAG1C,IAAI,CAAC,eAAe,IAAI,aAAa,GACnC;GAGF,MAAM,WACJ,SAAS,YACL,aAAa,QAAQ,YACrB,aAAa,QAAQ;GAE3B,IAAI,CAAC,UACH;GAGF,IAAI,kBAAkB,MAAM,YAC1B,MAAM,eAAe;GAGvB,IAAI,iBACF,MAAM,gBAAgB;GAGxB,SAAS;IACP,KAAK,MAAM;IACX;IACA,UAAU,iBACR,SACA,MAAM,UACN,eACA,IACF;IACA,SAAS,iBACP,WACA,MAAM,SACN,eACA,IACF;IACA,SAAS,iBAAiB,QAAQ,MAAM,SAAS,eAAe,IAAI;IACpE,QAAQ,iBAAiB,OAAO,MAAM,QAAQ,eAAe,IAAI;IACjE,QAAQ,MAAM;IACd,aAAa;GACf,CAAC;EACH;EAEA,MAAM,iBAAiB,UAAyB;GAC9C,oBAAoB,OAAO,SAAS;EACtC;EAEA,MAAM,eAAe,UAAyB;GAC5C,oBAAoB,OAAO,OAAO;EACpC;EAEA,MAAM,yBAAyB;GAC7B,YAAY,QAAQ,MAAM;EAC5B;EAEA,MAAM,+BAA+B;GACnC,IAAI,SAAS,oBAAoB,UAC/B,iBAAiB;EAErB;EAEA,OAAO,iBAAiB,WAAW,eAAe,IAAI;EACtD,OAAO,iBAAiB,SAAS,aAAa,IAAI;EAClD,OAAO,iBAAiB,QAAQ,gBAAgB;EAChD,SAAS,iBAAiB,oBAAoB,sBAAsB;EAEpE,aAAa;GACX,OAAO,oBAAoB,WAAW,eAAe,IAAI;GACzD,OAAO,oBAAoB,SAAS,aAAa,IAAI;GACrD,OAAO,oBAAoB,QAAQ,gBAAgB;GACnD,SAAS,oBAAoB,oBAAoB,sBAAsB;GAEvE,iBAAiB;EACnB;CACF,GAAG;EAAC;EAAS;EAAa;EAAe;EAAgB;CAAe,CAAC;AAC3E"}

package/dist/use-roving-focus.cjs

@@ -0,0 +1,93 @@
+"use client";
+let react = require("react");
+// src/use-roving-focus.ts
+const useRovingFocus = ({ items, orientation = "horizontal", dir = "ltr", loop = true, initialActiveId }) => {
+	const itemRefs = (0, react.useRef)(/* @__PURE__ */ new Map());
+	const callbackRefs = (0, react.useRef)(/* @__PURE__ */ new Map());
+	const itemsRef = (0, react.useRef)(items);
+	itemsRef.current = items;
+	const [activeId, setActiveId] = (0, react.useState)(() => {
+		return items.find((item) => item.id === initialActiveId && !item.disabled)?.id ?? items.find((item) => !item.disabled)?.id;
+	});
+	const resolvedActiveId = items.find((item) => item.id === activeId && !item.disabled)?.id ?? items.find((item) => !item.disabled)?.id;
+	(0, react.useEffect)(() => {
+		if (activeId !== resolvedActiveId) setActiveId(resolvedActiveId);
+	}, [activeId, resolvedActiveId]);
+	const getItemRef = (0, react.useCallback)((id) => {
+		const existingCallback = callbackRefs.current.get(id);
+		if (existingCallback) return existingCallback;
+		const callback = (node) => {
+			if (node) {
+				itemRefs.current.set(id, node);
+				return;
+			}
+			itemRefs.current.delete(id);
+			if (callbackRefs.current.get(id) === callback) callbackRefs.current.delete(id);
+		};
+		callbackRefs.current.set(id, callback);
+		return callback;
+	}, []);
+	const focusItem = (0, react.useCallback)((id) => {
+		const item = itemsRef.current.find((candidate) => candidate.id === id && !candidate.disabled);
+		const element = itemRefs.current.get(id);
+		if (!item || !element) return;
+		setActiveId(id);
+		element.focus();
+	}, []);
+	return {
+		activeId: resolvedActiveId,
+		getItemRef,
+		getItemTabIndex: (0, react.useCallback)((id, disabled = false) => {
+			if (disabled || resolvedActiveId === void 0) return -1;
+			return id === resolvedActiveId ? 0 : -1;
+		}, [resolvedActiveId]),
+		focusItem,
+		onItemFocus: (0, react.useCallback)((id) => {
+			if (itemsRef.current.find((candidate) => candidate.id === id && !candidate.disabled)) setActiveId(id);
+		}, []),
+		onItemKeyDown: (0, react.useCallback)((event, id) => {
+			if (event.defaultPrevented) return;
+			const enabledItems = itemsRef.current.filter((item) => !item.disabled);
+			if (enabledItems.length === 0) return;
+			const currentIndex = enabledItems.findIndex((item) => item.id === id);
+			if (currentIndex === -1) return;
+			let nextIndex;
+			let direction;
+			switch (event.key) {
+				case "Home":
+					nextIndex = 0;
+					break;
+				case "End":
+					nextIndex = enabledItems.length - 1;
+					break;
+				case "ArrowRight":
+					if (orientation === "horizontal" || orientation === "both") direction = dir === "rtl" ? -1 : 1;
+					break;
+				case "ArrowLeft":
+					if (orientation === "horizontal" || orientation === "both") direction = dir === "rtl" ? 1 : -1;
+					break;
+				case "ArrowDown":
+					if (orientation === "vertical" || orientation === "both") direction = 1;
+					break;
+				case "ArrowUp": if (orientation === "vertical" || orientation === "both") direction = -1;
+			}
+			if (direction !== void 0) {
+				const candidateIndex = currentIndex + direction;
+				nextIndex = loop ? (candidateIndex + enabledItems.length) % enabledItems.length : Math.min(Math.max(candidateIndex, 0), enabledItems.length - 1);
+			}
+			if (nextIndex === void 0) return;
+			const nextItem = enabledItems[nextIndex];
+			if (!nextItem) return;
+			event.preventDefault();
+			focusItem(nextItem.id);
+		}, [
+			dir,
+			focusItem,
+			loop,
+			orientation
+		])
+	};
+};
+exports.useRovingFocus = useRovingFocus;
+
+//# sourceMappingURL=use-roving-focus.cjs.map

package/dist/use-roving-focus.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-roving-focus.cjs","names":["useRef","useState","useCallback"],"sources":["../src/use-roving-focus.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  useCallback,\n  useEffect,\n  useRef,\n  useState,\n  type KeyboardEvent,\n  type RefCallback,\n} from \"react\";\n\nexport type RovingFocusOrientation = \"horizontal\" | \"vertical\" | \"both\";\n\nexport type RovingFocusItem = {\n  id: string;\n  disabled?: boolean;\n};\n\nexport type UseRovingFocusOptions = {\n  items: readonly RovingFocusItem[];\n  orientation?: RovingFocusOrientation;\n  dir?: \"ltr\" | \"rtl\";\n  loop?: boolean;\n  initialActiveId?: string;\n};\n\nexport type UseRovingFocusReturn<T extends HTMLElement> = {\n  activeId: string | undefined;\n  getItemRef: (id: string) => RefCallback<T>;\n  getItemTabIndex: (id: string, disabled?: boolean) => 0 | -1;\n  focusItem: (id: string) => void;\n  onItemFocus: (id: string) => void;\n  onItemKeyDown: (event: KeyboardEvent<T>, id: string) => void;\n};\n\nconst useRovingFocus = <T extends HTMLElement>({\n  items,\n  orientation = \"horizontal\",\n  dir = \"ltr\",\n  loop = true,\n  initialActiveId,\n}: UseRovingFocusOptions): UseRovingFocusReturn<T> => {\n  const itemRefs = useRef(new Map<string, T>());\n  const callbackRefs = useRef(new Map<string, RefCallback<T>>());\n  const itemsRef = useRef(items);\n\n  itemsRef.current = items;\n\n  const [activeId, setActiveId] = useState<string | undefined>(() => {\n    const initialItem = items.find(\n      (item) => item.id === initialActiveId && !item.disabled,\n    );\n\n    return initialItem?.id ?? items.find((item) => !item.disabled)?.id;\n  });\n\n  const resolvedActiveId =\n    items.find((item) => item.id === activeId && !item.disabled)?.id ??\n    items.find((item) => !item.disabled)?.id;\n\n  useEffect(() => {\n    if (activeId !== resolvedActiveId) {\n      setActiveId(resolvedActiveId);\n    }\n  }, [activeId, resolvedActiveId]);\n\n  const getItemRef = useCallback((id: string): RefCallback<T> => {\n    const existingCallback = callbackRefs.current.get(id);\n\n    if (existingCallback) {\n      return existingCallback;\n    }\n\n    const callback: RefCallback<T> = (node) => {\n      if (node) {\n        itemRefs.current.set(id, node);\n        return;\n      }\n\n      itemRefs.current.delete(id);\n\n      if (callbackRefs.current.get(id) === callback) {\n        callbackRefs.current.delete(id);\n      }\n    };\n\n    callbackRefs.current.set(id, callback);\n\n    return callback;\n  }, []);\n\n  const focusItem = useCallback((id: string) => {\n    const item = itemsRef.current.find(\n      (candidate) => candidate.id === id && !candidate.disabled,\n    );\n    const element = itemRefs.current.get(id);\n\n    if (!item || !element) {\n      return;\n    }\n\n    setActiveId(id);\n    element.focus();\n  }, []);\n\n  const getItemTabIndex = useCallback(\n    (id: string, disabled = false): 0 | -1 => {\n      if (disabled || resolvedActiveId === undefined) {\n        return -1;\n      }\n\n      return id === resolvedActiveId ? 0 : -1;\n    },\n    [resolvedActiveId],\n  );\n\n  const onItemFocus = useCallback((id: string) => {\n    const item = itemsRef.current.find(\n      (candidate) => candidate.id === id && !candidate.disabled,\n    );\n\n    if (item) {\n      setActiveId(id);\n    }\n  }, []);\n\n  const onItemKeyDown = useCallback(\n    (event: KeyboardEvent<T>, id: string) => {\n      if (event.defaultPrevented) {\n        return;\n      }\n\n      const enabledItems = itemsRef.current.filter((item) => !item.disabled);\n\n      if (enabledItems.length === 0) {\n        return;\n      }\n\n      const currentIndex = enabledItems.findIndex((item) => item.id === id);\n\n      if (currentIndex === -1) {\n        return;\n      }\n\n      let nextIndex: number | undefined;\n      let direction: number | undefined;\n\n      switch (event.key) {\n        case \"Home\":\n          nextIndex = 0;\n          break;\n\n        case \"End\":\n          nextIndex = enabledItems.length - 1;\n          break;\n\n        case \"ArrowRight\":\n          if (orientation === \"horizontal\" || orientation === \"both\") {\n            direction = dir === \"rtl\" ? -1 : 1;\n          }\n          break;\n\n        case \"ArrowLeft\":\n          if (orientation === \"horizontal\" || orientation === \"both\") {\n            direction = dir === \"rtl\" ? 1 : -1;\n          }\n          break;\n\n        case \"ArrowDown\":\n          if (orientation === \"vertical\" || orientation === \"both\") {\n            direction = 1;\n          }\n          break;\n\n        case \"ArrowUp\":\n          if (orientation === \"vertical\" || orientation === \"both\") {\n            direction = -1;\n          }\n          break;\n      }\n\n      if (direction !== undefined) {\n        const candidateIndex = currentIndex + direction;\n\n        nextIndex = loop\n          ? (candidateIndex + enabledItems.length) % enabledItems.length\n          : Math.min(Math.max(candidateIndex, 0), enabledItems.length - 1);\n      }\n\n      if (nextIndex === undefined) {\n        return;\n      }\n\n      const nextItem = enabledItems[nextIndex];\n\n      if (!nextItem) {\n        return;\n      }\n\n      event.preventDefault();\n      focusItem(nextItem.id);\n    },\n    [dir, focusItem, loop, orientation],\n  );\n\n  return {\n    activeId: resolvedActiveId,\n    getItemRef,\n    getItemTabIndex,\n    focusItem,\n    onItemFocus,\n    onItemKeyDown,\n  };\n};\n\nexport { useRovingFocus };\n"],"mappings":"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"}

package/dist/use-roving-focus.d.cts

@@ -0,0 +1,23 @@
+import { KeyboardEvent, RefCallback } from "react";
+export type RovingFocusOrientation = "horizontal" | "vertical" | "both";
+export type RovingFocusItem = {
+  id: string;
+  disabled?: boolean;
+};
+export type UseRovingFocusOptions = {
+  items: readonly RovingFocusItem[];
+  orientation?: RovingFocusOrientation;
+  dir?: "ltr" | "rtl";
+  loop?: boolean;
+  initialActiveId?: string;
+};
+export type UseRovingFocusReturn<T extends HTMLElement> = {
+  activeId: string | undefined;
+  getItemRef: (id: string) => RefCallback<T>;
+  getItemTabIndex: (id: string, disabled?: boolean) => 0 | -1;
+  focusItem: (id: string) => void;
+  onItemFocus: (id: string) => void;
+  onItemKeyDown: (event: KeyboardEvent<T>, id: string) => void;
+};
+declare const useRovingFocus: <T extends HTMLElement>({ items, orientation, dir, loop, initialActiveId }: UseRovingFocusOptions) => UseRovingFocusReturn<T>;
+export { useRovingFocus };

package/dist/use-roving-focus.d.ts

@@ -0,0 +1,23 @@
+import { KeyboardEvent, RefCallback } from "react";
+export type RovingFocusOrientation = "horizontal" | "vertical" | "both";
+export type RovingFocusItem = {
+  id: string;
+  disabled?: boolean;
+};
+export type UseRovingFocusOptions = {
+  items: readonly RovingFocusItem[];
+  orientation?: RovingFocusOrientation;
+  dir?: "ltr" | "rtl";
+  loop?: boolean;
+  initialActiveId?: string;
+};
+export type UseRovingFocusReturn<T extends HTMLElement> = {
+  activeId: string | undefined;
+  getItemRef: (id: string) => RefCallback<T>;
+  getItemTabIndex: (id: string, disabled?: boolean) => 0 | -1;
+  focusItem: (id: string) => void;
+  onItemFocus: (id: string) => void;
+  onItemKeyDown: (event: KeyboardEvent<T>, id: string) => void;
+};
+declare const useRovingFocus: <T extends HTMLElement>({ items, orientation, dir, loop, initialActiveId }: UseRovingFocusOptions) => UseRovingFocusReturn<T>;
+export { useRovingFocus };

package/dist/use-roving-focus.js

@@ -0,0 +1,93 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+// src/use-roving-focus.ts
+const useRovingFocus = ({ items, orientation = "horizontal", dir = "ltr", loop = true, initialActiveId }) => {
+	const itemRefs = useRef(/* @__PURE__ */ new Map());
+	const callbackRefs = useRef(/* @__PURE__ */ new Map());
+	const itemsRef = useRef(items);
+	itemsRef.current = items;
+	const [activeId, setActiveId] = useState(() => {
+		return items.find((item) => item.id === initialActiveId && !item.disabled)?.id ?? items.find((item) => !item.disabled)?.id;
+	});
+	const resolvedActiveId = items.find((item) => item.id === activeId && !item.disabled)?.id ?? items.find((item) => !item.disabled)?.id;
+	useEffect(() => {
+		if (activeId !== resolvedActiveId) setActiveId(resolvedActiveId);
+	}, [activeId, resolvedActiveId]);
+	const getItemRef = useCallback((id) => {
+		const existingCallback = callbackRefs.current.get(id);
+		if (existingCallback) return existingCallback;
+		const callback = (node) => {
+			if (node) {
+				itemRefs.current.set(id, node);
+				return;
+			}
+			itemRefs.current.delete(id);
+			if (callbackRefs.current.get(id) === callback) callbackRefs.current.delete(id);
+		};
+		callbackRefs.current.set(id, callback);
+		return callback;
+	}, []);
+	const focusItem = useCallback((id) => {
+		const item = itemsRef.current.find((candidate) => candidate.id === id && !candidate.disabled);
+		const element = itemRefs.current.get(id);
+		if (!item || !element) return;
+		setActiveId(id);
+		element.focus();
+	}, []);
+	return {
+		activeId: resolvedActiveId,
+		getItemRef,
+		getItemTabIndex: useCallback((id, disabled = false) => {
+			if (disabled || resolvedActiveId === void 0) return -1;
+			return id === resolvedActiveId ? 0 : -1;
+		}, [resolvedActiveId]),
+		focusItem,
+		onItemFocus: useCallback((id) => {
+			if (itemsRef.current.find((candidate) => candidate.id === id && !candidate.disabled)) setActiveId(id);
+		}, []),
+		onItemKeyDown: useCallback((event, id) => {
+			if (event.defaultPrevented) return;
+			const enabledItems = itemsRef.current.filter((item) => !item.disabled);
+			if (enabledItems.length === 0) return;
+			const currentIndex = enabledItems.findIndex((item) => item.id === id);
+			if (currentIndex === -1) return;
+			let nextIndex;
+			let direction;
+			switch (event.key) {
+				case "Home":
+					nextIndex = 0;
+					break;
+				case "End":
+					nextIndex = enabledItems.length - 1;
+					break;
+				case "ArrowRight":
+					if (orientation === "horizontal" || orientation === "both") direction = dir === "rtl" ? -1 : 1;
+					break;
+				case "ArrowLeft":
+					if (orientation === "horizontal" || orientation === "both") direction = dir === "rtl" ? 1 : -1;
+					break;
+				case "ArrowDown":
+					if (orientation === "vertical" || orientation === "both") direction = 1;
+					break;
+				case "ArrowUp": if (orientation === "vertical" || orientation === "both") direction = -1;
+			}
+			if (direction !== void 0) {
+				const candidateIndex = currentIndex + direction;
+				nextIndex = loop ? (candidateIndex + enabledItems.length) % enabledItems.length : Math.min(Math.max(candidateIndex, 0), enabledItems.length - 1);
+			}
+			if (nextIndex === void 0) return;
+			const nextItem = enabledItems[nextIndex];
+			if (!nextItem) return;
+			event.preventDefault();
+			focusItem(nextItem.id);
+		}, [
+			dir,
+			focusItem,
+			loop,
+			orientation
+		])
+	};
+};
+export { useRovingFocus };
+
+//# sourceMappingURL=use-roving-focus.js.map

package/dist/use-roving-focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-roving-focus.js","names":[],"sources":["../src/use-roving-focus.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  useCallback,\n  useEffect,\n  useRef,\n  useState,\n  type KeyboardEvent,\n  type RefCallback,\n} from \"react\";\n\nexport type RovingFocusOrientation = \"horizontal\" | \"vertical\" | \"both\";\n\nexport type RovingFocusItem = {\n  id: string;\n  disabled?: boolean;\n};\n\nexport type UseRovingFocusOptions = {\n  items: readonly RovingFocusItem[];\n  orientation?: RovingFocusOrientation;\n  dir?: \"ltr\" | \"rtl\";\n  loop?: boolean;\n  initialActiveId?: string;\n};\n\nexport type UseRovingFocusReturn<T extends HTMLElement> = {\n  activeId: string | undefined;\n  getItemRef: (id: string) => RefCallback<T>;\n  getItemTabIndex: (id: string, disabled?: boolean) => 0 | -1;\n  focusItem: (id: string) => void;\n  onItemFocus: (id: string) => void;\n  onItemKeyDown: (event: KeyboardEvent<T>, id: string) => void;\n};\n\nconst useRovingFocus = <T extends HTMLElement>({\n  items,\n  orientation = \"horizontal\",\n  dir = \"ltr\",\n  loop = true,\n  initialActiveId,\n}: UseRovingFocusOptions): UseRovingFocusReturn<T> => {\n  const itemRefs = useRef(new Map<string, T>());\n  const callbackRefs = useRef(new Map<string, RefCallback<T>>());\n  const itemsRef = useRef(items);\n\n  itemsRef.current = items;\n\n  const [activeId, setActiveId] = useState<string | undefined>(() => {\n    const initialItem = items.find(\n      (item) => item.id === initialActiveId && !item.disabled,\n    );\n\n    return initialItem?.id ?? items.find((item) => !item.disabled)?.id;\n  });\n\n  const resolvedActiveId =\n    items.find((item) => item.id === activeId && !item.disabled)?.id ??\n    items.find((item) => !item.disabled)?.id;\n\n  useEffect(() => {\n    if (activeId !== resolvedActiveId) {\n      setActiveId(resolvedActiveId);\n    }\n  }, [activeId, resolvedActiveId]);\n\n  const getItemRef = useCallback((id: string): RefCallback<T> => {\n    const existingCallback = callbackRefs.current.get(id);\n\n    if (existingCallback) {\n      return existingCallback;\n    }\n\n    const callback: RefCallback<T> = (node) => {\n      if (node) {\n        itemRefs.current.set(id, node);\n        return;\n      }\n\n      itemRefs.current.delete(id);\n\n      if (callbackRefs.current.get(id) === callback) {\n        callbackRefs.current.delete(id);\n      }\n    };\n\n    callbackRefs.current.set(id, callback);\n\n    return callback;\n  }, []);\n\n  const focusItem = useCallback((id: string) => {\n    const item = itemsRef.current.find(\n      (candidate) => candidate.id === id && !candidate.disabled,\n    );\n    const element = itemRefs.current.get(id);\n\n    if (!item || !element) {\n      return;\n    }\n\n    setActiveId(id);\n    element.focus();\n  }, []);\n\n  const getItemTabIndex = useCallback(\n    (id: string, disabled = false): 0 | -1 => {\n      if (disabled || resolvedActiveId === undefined) {\n        return -1;\n      }\n\n      return id === resolvedActiveId ? 0 : -1;\n    },\n    [resolvedActiveId],\n  );\n\n  const onItemFocus = useCallback((id: string) => {\n    const item = itemsRef.current.find(\n      (candidate) => candidate.id === id && !candidate.disabled,\n    );\n\n    if (item) {\n      setActiveId(id);\n    }\n  }, []);\n\n  const onItemKeyDown = useCallback(\n    (event: KeyboardEvent<T>, id: string) => {\n      if (event.defaultPrevented) {\n        return;\n      }\n\n      const enabledItems = itemsRef.current.filter((item) => !item.disabled);\n\n      if (enabledItems.length === 0) {\n        return;\n      }\n\n      const currentIndex = enabledItems.findIndex((item) => item.id === id);\n\n      if (currentIndex === -1) {\n        return;\n      }\n\n      let nextIndex: number | undefined;\n      let direction: number | undefined;\n\n      switch (event.key) {\n        case \"Home\":\n          nextIndex = 0;\n          break;\n\n        case \"End\":\n          nextIndex = enabledItems.length - 1;\n          break;\n\n        case \"ArrowRight\":\n          if (orientation === \"horizontal\" || orientation === \"both\") {\n            direction = dir === \"rtl\" ? -1 : 1;\n          }\n          break;\n\n        case \"ArrowLeft\":\n          if (orientation === \"horizontal\" || orientation === \"both\") {\n            direction = dir === \"rtl\" ? 1 : -1;\n          }\n          break;\n\n        case \"ArrowDown\":\n          if (orientation === \"vertical\" || orientation === \"both\") {\n            direction = 1;\n          }\n          break;\n\n        case \"ArrowUp\":\n          if (orientation === \"vertical\" || orientation === \"both\") {\n            direction = -1;\n          }\n          break;\n      }\n\n      if (direction !== undefined) {\n        const candidateIndex = currentIndex + direction;\n\n        nextIndex = loop\n          ? (candidateIndex + enabledItems.length) % enabledItems.length\n          : Math.min(Math.max(candidateIndex, 0), enabledItems.length - 1);\n      }\n\n      if (nextIndex === undefined) {\n        return;\n      }\n\n      const nextItem = enabledItems[nextIndex];\n\n      if (!nextItem) {\n        return;\n      }\n\n      event.preventDefault();\n      focusItem(nextItem.id);\n    },\n    [dir, focusItem, loop, orientation],\n  );\n\n  return {\n    activeId: resolvedActiveId,\n    getItemRef,\n    getItemTabIndex,\n    focusItem,\n    onItemFocus,\n    onItemKeyDown,\n  };\n};\n\nexport { useRovingFocus };\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@puzzle-ui/hooks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Reusable React hooks for Puzzle",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist",
+    "prepack": "tsdown"
+  },
+  "dependencies": {
+    "@puzzle-ui/core": "^0.2.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsdown": "^0.23.1",
+    "typescript": "^6.0.3"
+  }
+}