@negative-space/roving-focus 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matheus Bastani
+
+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/README.md

@@ -0,0 +1,15 @@
+# @negative-space/roving-focus
+
+A lightweight Roving Focus hook from Negative Space, enabling fully custom interactive navigation.
+
+## Installation
+
+    # Using Yarn
+    yarn add @negative-space/roving-focus
+
+    # Using npm
+    npm install @negative-space/roving-focus
+
+## Contributing
+
+Feel free to fork, tweak, and send a pull request!

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+import * as react from 'react';
+
+type RovingFocusItem<Id extends string = string> = {
+    id: Id;
+    ref: React.RefObject<HTMLElement>;
+    disabled?: boolean;
+};
+declare const useRovingFocus: <Item extends RovingFocusItem<Id>, Id extends string = string>() => {
+    registerItem: (item: Item) => void;
+    unregisterItem: (id: Id) => void;
+    activeId: Id | null;
+    setActiveId: react.Dispatch<react.SetStateAction<Id | null>>;
+    onKeyDown: (event: React.KeyboardEvent) => void;
+    onFocus: (event: React.FocusEvent) => void;
+    onBlur: (event: React.FocusEvent) => void;
+};
+
+export { type RovingFocusItem, useRovingFocus };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import * as react from 'react';
+
+type RovingFocusItem<Id extends string = string> = {
+    id: Id;
+    ref: React.RefObject<HTMLElement>;
+    disabled?: boolean;
+};
+declare const useRovingFocus: <Item extends RovingFocusItem<Id>, Id extends string = string>() => {
+    registerItem: (item: Item) => void;
+    unregisterItem: (id: Id) => void;
+    activeId: Id | null;
+    setActiveId: react.Dispatch<react.SetStateAction<Id | null>>;
+    onKeyDown: (event: React.KeyboardEvent) => void;
+    onFocus: (event: React.FocusEvent) => void;
+    onBlur: (event: React.FocusEvent) => void;
+};
+
+export { type RovingFocusItem, useRovingFocus };

package/dist/index.js

@@ -0,0 +1,67 @@
+'use strict';
+
+var react = require('react');
+
+// src/index.ts
+var useRovingFocus = () => {
+  const items = react.useRef([]);
+  const [activeId, setActiveId] = react.useState(null);
+  const registerItem = react.useCallback((item) => {
+    if (items.current.some((i) => i.id === item.id)) return;
+    items.current = [...items.current, item];
+  }, []);
+  const unregisterItem = react.useCallback((id) => {
+    items.current = items.current.filter((i) => i.id !== id);
+  }, []);
+  const focusItem = react.useCallback((item) => {
+    if (!item || item.disabled) return;
+    setActiveId(item.id);
+    item.ref.current?.focus();
+  }, []);
+  const moveFocus = react.useCallback(
+    (offset) => {
+      const enabled = items.current.filter((i) => !i.disabled);
+      if (!enabled.length) return;
+      const index = enabled.findIndex((i) => i.id === activeId);
+      const nextIndex = index === -1 ? 0 : (index + offset + enabled.length) % enabled.length;
+      focusItem(enabled[nextIndex]);
+    },
+    [activeId, focusItem]
+  );
+  const onKeyDown = react.useCallback(
+    (event) => {
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        moveFocus(1);
+      }
+      if (event.key === "ArrowUp") {
+        event.preventDefault();
+        moveFocus(-1);
+      }
+    },
+    [moveFocus]
+  );
+  const onFocus = react.useCallback((event) => {
+    if (event.target === event.currentTarget) {
+      setActiveId(null);
+    }
+  }, []);
+  const onBlur = react.useCallback((event) => {
+    if (!event.currentTarget.contains(event.relatedTarget)) {
+      setActiveId(null);
+    }
+  }, []);
+  return {
+    registerItem,
+    unregisterItem,
+    activeId,
+    setActiveId,
+    onKeyDown,
+    onFocus,
+    onBlur
+  };
+};
+
+exports.useRovingFocus = useRovingFocus;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["useRef","useState","useCallback"],"mappings":"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","file":"index.js","sourcesContent":["import { useCallback, useRef, useState } from 'react'\n\nexport type RovingFocusItem<Id extends string = string> = {\n  id: Id\n  ref: React.RefObject<HTMLElement>\n  disabled?: boolean\n}\n\nexport const useRovingFocus = <Item extends RovingFocusItem<Id>, Id extends string = string>() => {\n  const items = useRef<Item[]>([])\n  const [activeId, setActiveId] = useState<Id | null>(null)\n\n  const registerItem = useCallback((item: Item) => {\n    if (items.current.some((i) => i.id === item.id)) return\n    items.current = [...items.current, item]\n  }, [])\n\n  const unregisterItem = useCallback((id: Id) => {\n    items.current = items.current.filter((i) => i.id !== id)\n  }, [])\n\n  const focusItem = useCallback((item?: Item) => {\n    if (!item || item.disabled) return\n    setActiveId(item.id)\n    item.ref.current?.focus()\n  }, [])\n\n  const moveFocus = useCallback(\n    (offset: number) => {\n      const enabled = items.current.filter((i) => !i.disabled)\n      if (!enabled.length) return\n\n      const index = enabled.findIndex((i) => i.id === activeId)\n      const nextIndex = index === -1 ? 0 : (index + offset + enabled.length) % enabled.length\n\n      focusItem(enabled[nextIndex])\n    },\n    [activeId, focusItem]\n  )\n\n  const onKeyDown = useCallback(\n    (event: React.KeyboardEvent) => {\n      if (event.key === 'ArrowDown') {\n        event.preventDefault()\n        moveFocus(1)\n      }\n      if (event.key === 'ArrowUp') {\n        event.preventDefault()\n        moveFocus(-1)\n      }\n    },\n    [moveFocus]\n  )\n\n  const onFocus = useCallback((event: React.FocusEvent) => {\n    if (event.target === event.currentTarget) {\n      setActiveId(null)\n    }\n  }, [])\n\n  const onBlur = useCallback((event: React.FocusEvent) => {\n    if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {\n      setActiveId(null)\n    }\n  }, [])\n\n  return {\n    registerItem,\n    unregisterItem,\n    activeId,\n    setActiveId,\n    onKeyDown,\n    onFocus,\n    onBlur\n  }\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,65 @@
+import { useRef, useState, useCallback } from 'react';
+
+// src/index.ts
+var useRovingFocus = () => {
+  const items = useRef([]);
+  const [activeId, setActiveId] = useState(null);
+  const registerItem = useCallback((item) => {
+    if (items.current.some((i) => i.id === item.id)) return;
+    items.current = [...items.current, item];
+  }, []);
+  const unregisterItem = useCallback((id) => {
+    items.current = items.current.filter((i) => i.id !== id);
+  }, []);
+  const focusItem = useCallback((item) => {
+    if (!item || item.disabled) return;
+    setActiveId(item.id);
+    item.ref.current?.focus();
+  }, []);
+  const moveFocus = useCallback(
+    (offset) => {
+      const enabled = items.current.filter((i) => !i.disabled);
+      if (!enabled.length) return;
+      const index = enabled.findIndex((i) => i.id === activeId);
+      const nextIndex = index === -1 ? 0 : (index + offset + enabled.length) % enabled.length;
+      focusItem(enabled[nextIndex]);
+    },
+    [activeId, focusItem]
+  );
+  const onKeyDown = useCallback(
+    (event) => {
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        moveFocus(1);
+      }
+      if (event.key === "ArrowUp") {
+        event.preventDefault();
+        moveFocus(-1);
+      }
+    },
+    [moveFocus]
+  );
+  const onFocus = useCallback((event) => {
+    if (event.target === event.currentTarget) {
+      setActiveId(null);
+    }
+  }, []);
+  const onBlur = useCallback((event) => {
+    if (!event.currentTarget.contains(event.relatedTarget)) {
+      setActiveId(null);
+    }
+  }, []);
+  return {
+    registerItem,
+    unregisterItem,
+    activeId,
+    setActiveId,
+    onKeyDown,
+    onFocus,
+    onBlur
+  };
+};
+
+export { useRovingFocus };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import { useCallback, useRef, useState } from 'react'\n\nexport type RovingFocusItem<Id extends string = string> = {\n  id: Id\n  ref: React.RefObject<HTMLElement>\n  disabled?: boolean\n}\n\nexport const useRovingFocus = <Item extends RovingFocusItem<Id>, Id extends string = string>() => {\n  const items = useRef<Item[]>([])\n  const [activeId, setActiveId] = useState<Id | null>(null)\n\n  const registerItem = useCallback((item: Item) => {\n    if (items.current.some((i) => i.id === item.id)) return\n    items.current = [...items.current, item]\n  }, [])\n\n  const unregisterItem = useCallback((id: Id) => {\n    items.current = items.current.filter((i) => i.id !== id)\n  }, [])\n\n  const focusItem = useCallback((item?: Item) => {\n    if (!item || item.disabled) return\n    setActiveId(item.id)\n    item.ref.current?.focus()\n  }, [])\n\n  const moveFocus = useCallback(\n    (offset: number) => {\n      const enabled = items.current.filter((i) => !i.disabled)\n      if (!enabled.length) return\n\n      const index = enabled.findIndex((i) => i.id === activeId)\n      const nextIndex = index === -1 ? 0 : (index + offset + enabled.length) % enabled.length\n\n      focusItem(enabled[nextIndex])\n    },\n    [activeId, focusItem]\n  )\n\n  const onKeyDown = useCallback(\n    (event: React.KeyboardEvent) => {\n      if (event.key === 'ArrowDown') {\n        event.preventDefault()\n        moveFocus(1)\n      }\n      if (event.key === 'ArrowUp') {\n        event.preventDefault()\n        moveFocus(-1)\n      }\n    },\n    [moveFocus]\n  )\n\n  const onFocus = useCallback((event: React.FocusEvent) => {\n    if (event.target === event.currentTarget) {\n      setActiveId(null)\n    }\n  }, [])\n\n  const onBlur = useCallback((event: React.FocusEvent) => {\n    if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {\n      setActiveId(null)\n    }\n  }, [])\n\n  return {\n    registerItem,\n    unregisterItem,\n    activeId,\n    setActiveId,\n    onKeyDown,\n    onFocus,\n    onBlur\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@negative-space/roving-focus",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Roving focus hook by Negative Space, providing interactive behavior without visual constraints",
+  "keywords": [
+    "hook",
+    "keyboard",
+    "negative-space",
+    "nsui",
+    "react",
+    "roving-focus"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/negative-space-ui/nsui",
+    "directory": "packages/core/roving-focus"
+  },
+  "bugs": {
+    "url": "https://github.com/negative-space-ui/nsui/issues"
+  },
+  "peerDependencies": {
+    "react": "^19.2.3"
+  },
+  "clean-package": "../../../../clean-package.config.json",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist .turbo",
+    "dev": "pnpm build:fast --watch",
+    "lint": "eslint . --ext ts,tsx",
+    "typecheck": "tsc --noEmit"
+  }
+}