Skip to content

Commit d2c24ad

Browse files
chrsgrrttchrsgrrtt
committed
Add initial release
1 parent 287cfeb commit d2c24ad

File tree

8 files changed

+167
-31
lines changed

8 files changed

+167
-31
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Build and Publish on Release
2+
3+
on:
4+
release:
5+
types: [created]
6+
7+
jobs:
8+
build-and-publish:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout code
12+
uses: actions/checkout@v4
13+
14+
- uses: oven-sh/setup-bun@v1
15+
with:
16+
bun-version: latest
17+
18+
- name: Install Dependencies
19+
run: bun install --frozen-lockfile
20+
21+
- name: Build and prepare package for npm
22+
run: bun package.ts
23+
24+
- uses: JS-DevTools/npm-publish@v3
25+
with:
26+
token: ${{ secrets.NPM_TOKEN }}
27+
package: package/package.json
28+
access: public
29+

‎README.md‎

Lines changed: 22 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
# @hyperlaunch/react-use-virtual-cursor
1+
# @hyperlaunch/use-virtual-cursor
22

3-
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.
3+
The `useVirtualCursor` hook creates a virtual cursor that can be moved freely within the viewport via arrow key presses, and trigger click events on elements like buttons and links via 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.
44

55
## Installation
66

77
Install the package via npm or yarn:
88

99
```bash
10-
npm install @hyperlaunch/react-use-virtual-cursor
10+
npm install @hyperlaunch/use-virtual-cursor
1111
# or
12-
pnpm add @hyperlaunch/react-use-virtual-cursor
12+
pnpm add @hyperlaunch/use-virtual-cursor
1313
# or
14-
bun add @hyperlaunch/react-use-virtual-cursor
14+
bun add @hyperlaunch/use-virtual-cursor
1515
```
1616

1717
## Usage
@@ -27,35 +27,34 @@ To use the `useVirtualCursor` hook, add it to your React component by attaching
2727
- **cursorRef** (`React.RefObject<HTMLDivElement>`): A ref to be attached to the cursor element, allowing the hook to manage its position based on keyboard interactions.
2828
- **position** (`{ x: number, y: number }`): The current x and y coordinates of the cursor, useful for positioning the cursor element in an absolute layout.
2929
- **canInteract** (`boolean`): Indicates whether the cursor is currently over an interactive element like links or buttons, enabling dynamic styling changes.
30+
- **suggestedStyles** (`React.CSSProperties`): Position related styles to control the onscreen position of the cursor element (ie. `top`, `left`, `z-index`). These are suggested, so can be overridden if required.
3031

3132
The cursor will be positioned in the center of the screen, initially.
3233

3334
### Example
3435

35-
Here’s an example of how to use `useVirtualCursor` in a component:
36+
Here’s an example of how to use `useVirtualCursor` in a component with [Tailwind CSS](https://tailwindcss.com/) for styles:
3637

3738
```jsx
38-
function Cursor() {
39-
const { cursorRef, position, canInteract } = useVirtualCursor({
40-
moveMultiplier: 0.8
41-
});
39+
import useVirtualCursor from "@hyperlaunch/use-virtual-cursor";
4240

43-
const classNames = `
44-
absolute pointer-events-none fixed h-8 w-8 rounded-full transition-transform duration-200 z-50
45-
${canInteract ? "bg-gray-500 border-2 border-white ring-1 ring-gray-400 shadow-lg origin-center scale-75" : "bg-gray-900/40"}
41+
function Cursor() {
42+
const { cursorRef, canInteract, suggestedStyles } = useVirtualCursor({
43+
moveMultiplier: 0.8,
44+
});
45+
46+
const classNames = `
47+
pointer-events-none fixed h-8 w-8 rounded-full transition-transform duration-200
48+
${
49+
canInteract
50+
? "bg-gray-500 border-2 border-white ring-1 ring-gray-400 shadow-lg origin-center scale-75"
51+
: "bg-gray-900/40"
52+
}
4653
`;
4754

48-
return (
49-
<div
50-
ref={cursorRef}
51-
className={classNames}
52-
style={{
53-
left: `${position.x}px`,
54-
top: `${position.y}px`
55-
}}
56-
/>
57-
);
55+
return <div style={suggestedStyles} ref={cursorRef} className={classNames} />;
5856
}
57+
5958
```
6059

6160
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.

‎bun.lockb‎

7.25 KB
Binary file not shown.

‎package.json‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,28 @@
11
{
2-
"name": "use-virtual-cursor",
3-
"module": "src/index.ts",
2+
"name": "@hyperlaunch/use-virtual-cursor",
3+
"version": "0.1.0",
4+
"main": "src/index.ts",
45
"type": "module",
6+
"files": ["src/**/*"],
7+
"scripts": {
8+
"build": "bun build.ts"
9+
},
10+
"repository": {
11+
"type": "git",
12+
"url": "git+https://github.com/hyperlaunch/use-virtual-cursor.git"
13+
},
14+
"author": "Chris Garrett <[email protected]>",
15+
"license": "MIT",
16+
"private": false,
517
"devDependencies": {
618
"@biomejs/biome": "^1.7.1",
719
"@types/bun": "latest",
820
"@types/react": "^18.2.79",
9-
"react": "^18.2.0"
21+
"bun-plugin-dts": "^0.2.3",
22+
"react": "^18.2.0",
23+
"typescript": "^5.4.5"
1024
},
1125
"peerDependencies": {
12-
"react": "^18.2.0",
13-
"typescript": "^5.0.0"
26+
"react": "^18.2.0"
1427
}
1528
}

‎package.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import dts from "bun-plugin-dts";
2+
3+
const packageJson = await Bun.file("package.json").json();
4+
const packageDist = {
5+
...packageJson,
6+
main: "dist/index.js",
7+
modules: "dist/index.js",
8+
typings: "dist/index.d.ts",
9+
type: "module",
10+
files: ["dist/**/*"],
11+
};
12+
await Bun.write("package/package.json", JSON.stringify(packageDist));
13+
14+
await Bun.write("package/README.md", Bun.file("README.md"));
15+
16+
await Bun.build({
17+
entrypoints: ["./src/index.ts"],
18+
outdir: "./package/dist",
19+
external: ["react"],
20+
plugins: [dts()],
21+
});

‎package/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# @hyperlaunch/use-virtual-cursor
2+
3+
The `useVirtualCursor` hook creates a virtual cursor that can be moved freely within the viewport via arrow key presses, and trigger click events on elements like buttons and links via 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.
4+
5+
## Installation
6+
7+
Install the package via npm or yarn:
8+
9+
```bash
10+
npm install @hyperlaunch/use-virtual-cursor
11+
# or
12+
pnpm add @hyperlaunch/use-virtual-cursor
13+
# or
14+
bun add @hyperlaunch/use-virtual-cursor
15+
```
16+
17+
## Usage
18+
19+
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.
20+
21+
### Arguments
22+
23+
- **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.
24+
25+
### Returns
26+
27+
- **cursorRef** (`React.RefObject<HTMLDivElement>`): A ref to be attached to the cursor element, allowing the hook to manage its position based on keyboard interactions.
28+
- **position** (`{ x: number, y: number }`): The current x and y coordinates of the cursor, useful for positioning the cursor element in an absolute layout.
29+
- **canInteract** (`boolean`): Indicates whether the cursor is currently over an interactive element like links or buttons, enabling dynamic styling changes.
30+
- **suggestedStyles** (`React.CSSProperties`): Position related styles to control the onscreen position of the cursor element (ie. `top`, `left`, `z-index`). These are suggested, so can be overridden if required.
31+
32+
The cursor will be positioned in the center of the screen, initially.
33+
34+
### Example
35+
36+
Here’s an example of how to use `useVirtualCursor` in a component with [Tailwind CSS](https://tailwindcss.com/) for styles:
37+
38+
```jsx
39+
import useVirtualCursor from "@hyperlaunch/use-virtual-cursor";
40+
41+
function Cursor() {
42+
const { cursorRef, canInteract, suggestedStyles } = useVirtualCursor({
43+
moveMultiplier: 0.8,
44+
});
45+
46+
const classNames = `
47+
pointer-events-none fixed h-8 w-8 rounded-full transition-transform duration-200
48+
${
49+
canInteract
50+
? "bg-gray-500 border-2 border-white ring-1 ring-gray-400 shadow-lg origin-center scale-75"
51+
: "bg-gray-900/40"
52+
}
53+
`;
54+
55+
return <div style={suggestedStyles} ref={cursorRef} className={classNames} />;
56+
}
57+
58+
```
59+
60+
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.

‎package/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{"name":"@hyperlaunch/use-virtual-cursor","version":"0.0.5","main":"dist/index.js","type":"module","files":["dist/**/*"],"scripts":{"build":"bun build.ts"},"repository":{"type":"git","url":"git+https://github.com/hyperlaunch/use-virtual-cursor.git"},"author":"Chris Garrett <[email protected]>","license":"MIT","private":false,"devDependencies":{"@biomejs/biome":"^1.7.1","@types/bun":"latest","@types/react":"^18.2.79","bun-plugin-dts":"^0.2.3","react":"^18.2.0","typescript":"^5.4.5"},"peerDependencies":{"react":"^18.2.0"},"modules":"dist/index.js","typings":"dist/index.d.ts"}

‎src/index.ts‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
1-
import { useCallback, useEffect, useRef, useState } from "react";
1+
import {
2+
useCallback,
3+
useEffect,
4+
useRef,
5+
useState,
6+
type CSSProperties,
7+
} from "react";
28
import findNearestClickableElement from "./utils/find-nearest-clickable-element";
39
import getLiveCursorPosition from "./utils/get-live-cursor-position";
410
import calculateNextPosition from "./utils/calculate-next-position";
@@ -12,7 +18,7 @@ function simulateClick({ x, y }: { x: number; y: number }) {
1218
if (element instanceof HTMLElement) return element.click();
1319
}
1420

15-
export default function useVirtualCursor({
21+
export function useVirtualCursor({
1622
moveMultiplier = 1,
1723
}: { moveMultiplier?: number }) {
1824
const cursorRef = useRef<HTMLDivElement>(null);
@@ -84,5 +90,12 @@ export default function useVirtualCursor({
8490
}
8591
}, [position]);
8692

87-
return { cursorRef, position, setPosition, canInteract, cursorDimensions };
93+
const suggestedStyles: CSSProperties = {
94+
position: "absolute",
95+
zIndex: 9999,
96+
left: `${position.x}px`,
97+
top: `${position.y}px`,
98+
};
99+
100+
return { cursorRef, position, canInteract, suggestedStyles };
88101
}

0 commit comments

Comments
 (0)