Add initial hook

Author: chrsgrrtt

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.gitignore

@@ -0,0 +1,127 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chris Garrett
+
+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.

README.md

@@ -0,0 +1,61 @@
+# @hyperlaunch/react-use-virtual-cursor
+
+The useVirtualCursor hook creates a virtual cursor that can be moved freely within the viewport with arrow key presses, and trigger click events on elements like buttons and links with the enter key. It's designed for environments such as touch screen kiosks, allowing D-pad navigation to enhance accessibility without requiring additional UI modifications.
+
+## Installation
+
+Install the package via npm or yarn:
+
+```bash
+npm install @hyperlaunch/react-use-virtual-cursor
+# or
+pnpm add @hyperlaunch/react-use-virtual-cursor
+# or
+bun add @hyperlaunch/react-use-virtual-cursor
+```
+
+## Usage
+
+To use the `useVirtualCursor` hook, add it to your React component by attaching the `cursorRef` to the element you want to control, and using `position` to update the elements position. Configure the movement speed through the `moveMultiplier`, which scales the cursor's movement relative to its width for each key press.
+
+### Arguments
+
+- **moveMultiplier** (`number`): Adjusts the scale of movement of the cursor. The movement distance per arrow key press is calculated as a fraction of the cursor's width, allowing for adjustable responsiveness.
+
+### Returns
+
+- **cursorRef** (`React.RefObject<HTMLDivElement>`): A ref to be attached to the cursor element, allowing the hook to manage its position based on keyboard interactions.
+- **position** (`{ x: number, y: number }`): The current x and y coordinates of the cursor, useful for positioning the cursor element in an absolute layout.
+- **canInteract** (`boolean`): Indicates whether the cursor is currently over an interactive element like links or buttons, enabling dynamic styling changes.
+
+The cursor will be positioned in the center of the screen, initially.
+
+### Example
+
+Here’s an example of how to use `useVirtualCursor` in a component:
+
+```jsx
+function Cursor() {
+  const { cursorRef, position, canInteract } = useVirtualCursor({
+    moveMultiplier: 0.8
+  });
+
+  const classNames = `
+    absolute pointer-events-none fixed h-8 w-8 rounded-full transition-transform duration-200 z-50
+    ${canInteract ? "bg-gray-500 border-2 border-white ring-1 ring-gray-400 shadow-lg origin-center scale-75" : "bg-gray-900/40"}
+  `;
+
+  return (
+    <div
+      ref={cursorRef}
+      className={classNames}
+      style={{
+        left: `${position.x}px`,
+        top: `${position.y}px`
+      }}
+    />
+  );
+}
+```
+
+This component sets up a custom cursor that responds to keyboard inputs. It applies contextual class names if the cursor is over interactive elements, demonstrating how `useVirtualCursor` can be applied to enhance accessibility and interactivity in your React applications.

biome.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.7.1/schema.json",
+	"organizeImports": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	}
+}

bun.lockb

@@ -0,0 +1,15 @@
+{
+	"name": "use-virtual-cursor",
+	"module": "src/index.ts",
+	"type": "module",
+	"devDependencies": {
+		"@biomejs/biome": "^1.7.1",
+		"@types/bun": "latest",
+		"@types/react": "^18.2.79",
+		"react": "^18.2.0"
+	},
+	"peerDependencies": {
+		"react": "^18.2.0",
+		"typescript": "^5.0.0"
+	}
+}

package.json

@@ -0,0 +1,88 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import findNearestClickableElement from "./utils/find-nearest-clickable-element";
+import getLiveCursorPosition from "./utils/get-live-cursor-position";
+import calculateNextPosition from "./utils/calculate-next-position";
+import isElementOutOfViewport from "./utils/is-element-out-of-viewport";
+
+const ArrowKeys = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"];
+
+function simulateClick({ x, y }: { x: number; y: number }) {
+	const element = findNearestClickableElement({ x, y });
+
+	if (element instanceof HTMLElement) return element.click();
+}
+
+export default function useVirtualCursor({
+	moveMultiplier = 1,
+}: { moveMultiplier?: number }) {
+	const cursorRef = useRef<HTMLDivElement>(null);
+	const [position, setPosition] = useState({ x: 0, y: 0 });
+	const [canInteract, setcanInteract] = useState<boolean>(false);
+	const [cursorDimensions, setCursorDimensions] = useState({
+		width: 0,
+		height: 0,
+	});
+
+	const handleKeyPress = useCallback(
+		(e: KeyboardEvent) => {
+			if (!cursorDimensions || !moveMultiplier || !position) return;
+
+			const key = e.key;
+
+			if (ArrowKeys.includes(key))
+				return setPosition((currentPosition) => {
+					const nextPosition = calculateNextPosition({
+						currentPosition,
+						cursorDimensions,
+						moveMultiplier,
+						key,
+					});
+
+					if (
+						!nextPosition ||
+						isElementOutOfViewport({ position: nextPosition, cursorDimensions })
+					)
+						return currentPosition;
+
+					return nextPosition;
+				});
+
+			if (key === "Enter" && cursorRef.current)
+				return simulateClick(getLiveCursorPosition(cursorRef.current));
+		},
+		[cursorDimensions, moveMultiplier, position],
+	);
+
+	useEffect(() => {
+		window.addEventListener("keydown", handleKeyPress);
+
+		return () => window.removeEventListener("keydown", handleKeyPress);
+	}, [handleKeyPress]);
+
+	// Set the cursor in the center of the screen initially
+	useEffect(() => {
+		if (!cursorRef.current) return;
+
+		const { width, height } = cursorRef.current.getBoundingClientRect();
+
+		setCursorDimensions({ width, height });
+
+		setPosition({
+			x: (window.innerWidth - width) / 2,
+			y: (window.innerHeight - height) / 2,
+		});
+	}, []);
+
+	// Update state of cursor is/isn't over clickable element
+	// biome-ignore lint/correctness/useExhaustiveDependencies: triggered by changes to position
+	useEffect(() => {
+		if (cursorRef.current) {
+			const cursorPosition = getLiveCursorPosition(cursorRef.current);
+			const element = findNearestClickableElement(cursorPosition);
+
+			setcanInteract(Boolean(element));
+		}
+	}, [position]);
+
+	return { cursorRef, position, setPosition, canInteract, cursorDimensions };
+}

src/index.ts

@@ -0,0 +1,25 @@
+export default function calculateNextPosition({
+	currentPosition,
+	cursorDimensions,
+	moveMultiplier,
+	key,
+}: {
+	currentPosition: { x: number; y: number };
+	cursorDimensions: { width: number; height: number };
+	moveMultiplier: number;
+	key: string;
+}) {
+	const increment =
+		Math.max(cursorDimensions.width, cursorDimensions.height) * moveMultiplier;
+
+	if (key === "ArrowUp")
+		return { ...currentPosition, y: currentPosition.y - increment };
+	if (key === "ArrowDown")
+		return { ...currentPosition, y: currentPosition.y + increment };
+	if (key === "ArrowLeft")
+		return { ...currentPosition, x: currentPosition.x - increment };
+	if (key === "ArrowRight")
+		return { ...currentPosition, x: currentPosition.x + increment };
+
+	return currentPosition;
+}

src/utils/calculate-next-position.ts

@@ -0,0 +1,18 @@
+function findNearestElements({ x, y }: { x: number; y: number }) {
+	return document.elementsFromPoint(x, y);
+}
+
+function clickable(element: Element) {
+	return element.matches(
+		'a, button, input[type="button"], input[type="submit"], [onclick], [role="button"]',
+	);
+}
+
+export default function findNearestClickableElement(position: {
+	x: number;
+	y: number;
+}): Element | undefined {
+	const elements = findNearestElements(position);
+
+	return [...(elements || [])].find(clickable);
+}