diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..e0d709f --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,29 @@ +name: Build and Publish on Release + +on: + release: + types: [created] + +jobs: + build-and-publish: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - uses: oven-sh/setup-bun@v1 + with: + bun-version: latest + + - name: Install Dependencies + run: bun install --frozen-lockfile + + - name: Build and prepare package for npm + run: bun package.ts + + - uses: JS-DevTools/npm-publish@v3 + with: + token: ${{ secrets.NPM_TOKEN }} + package: package/package.json + access: public + diff --git a/README.md b/README.md index 9a88df8..669ee28 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,17 @@ -# @hyperlaunch/react-use-virtual-cursor +# @hyperlaunch/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. +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. ## Installation Install the package via npm or yarn: ```bash -npm install @hyperlaunch/react-use-virtual-cursor +npm install @hyperlaunch/use-virtual-cursor # or -pnpm add @hyperlaunch/react-use-virtual-cursor +pnpm add @hyperlaunch/use-virtual-cursor # or -bun add @hyperlaunch/react-use-virtual-cursor +bun add @hyperlaunch/use-virtual-cursor ``` ## Usage @@ -27,35 +27,34 @@ To use the `useVirtualCursor` hook, add it to your React component by attaching - **cursorRef** (`React.RefObject`): 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. +- **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. 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: +Here’s an example of how to use `useVirtualCursor` in a component with [Tailwind CSS](https://tailwindcss.com/) for styles: ```jsx -function Cursor() { - const { cursorRef, position, canInteract } = useVirtualCursor({ - moveMultiplier: 0.8 - }); +import useVirtualCursor from "@hyperlaunch/use-virtual-cursor"; - 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"} +function Cursor() { + const { cursorRef, canInteract, suggestedStyles } = useVirtualCursor({ + moveMultiplier: 0.8, + }); + + const classNames = ` + pointer-events-none fixed h-8 w-8 rounded-full transition-transform duration-200 + ${ + canInteract + ? "bg-gray-500 border-2 border-white ring-1 ring-gray-400 shadow-lg origin-center scale-75" + : "bg-gray-900/40" + } `; - return ( -
- ); + return
; } + ``` 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. \ No newline at end of file diff --git a/bun.lockb b/bun.lockb index fcedb5d..f8839e2 100644 Binary files a/bun.lockb and b/bun.lockb differ diff --git a/package.json b/package.json index 5d335b6..c5d6bb7 100644 --- a/package.json +++ b/package.json @@ -1,15 +1,28 @@ { - "name": "use-virtual-cursor", - "module": "src/index.ts", + "name": "@hyperlaunch/use-virtual-cursor", + "version": "0.1.0", + "main": "src/index.ts", "type": "module", + "files": ["src/**/*"], + "scripts": { + "build": "bun build.ts" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/hyperlaunch/use-virtual-cursor.git" + }, + "author": "Chris Garrett ", + "license": "MIT", + "private": false, "devDependencies": { "@biomejs/biome": "^1.7.1", "@types/bun": "latest", "@types/react": "^18.2.79", - "react": "^18.2.0" + "bun-plugin-dts": "^0.2.3", + "react": "^18.2.0", + "typescript": "^5.4.5" }, "peerDependencies": { - "react": "^18.2.0", - "typescript": "^5.0.0" + "react": "^18.2.0" } } diff --git a/package.ts b/package.ts new file mode 100644 index 0000000..ec06979 --- /dev/null +++ b/package.ts @@ -0,0 +1,21 @@ +import dts from "bun-plugin-dts"; + +const packageJson = await Bun.file("package.json").json(); +const packageDist = { + ...packageJson, + main: "dist/index.js", + modules: "dist/index.js", + typings: "dist/index.d.ts", + type: "module", + files: ["dist/**/*"], +}; +await Bun.write("package/package.json", JSON.stringify(packageDist)); + +await Bun.write("package/README.md", Bun.file("README.md")); + +await Bun.build({ + entrypoints: ["./src/index.ts"], + outdir: "./package/dist", + external: ["react"], + plugins: [dts()], +}); diff --git a/package/README.md b/package/README.md new file mode 100644 index 0000000..669ee28 --- /dev/null +++ b/package/README.md @@ -0,0 +1,60 @@ +# @hyperlaunch/use-virtual-cursor + +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. + +## Installation + +Install the package via npm or yarn: + +```bash +npm install @hyperlaunch/use-virtual-cursor +# or +pnpm add @hyperlaunch/use-virtual-cursor +# or +bun add @hyperlaunch/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`): 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. +- **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. + +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 with [Tailwind CSS](https://tailwindcss.com/) for styles: + +```jsx +import useVirtualCursor from "@hyperlaunch/use-virtual-cursor"; + +function Cursor() { + const { cursorRef, canInteract, suggestedStyles } = useVirtualCursor({ + moveMultiplier: 0.8, + }); + + const classNames = ` + pointer-events-none fixed h-8 w-8 rounded-full transition-transform duration-200 + ${ + canInteract + ? "bg-gray-500 border-2 border-white ring-1 ring-gray-400 shadow-lg origin-center scale-75" + : "bg-gray-900/40" + } + `; + + return
; +} + +``` + +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. \ No newline at end of file diff --git a/package/package.json b/package/package.json new file mode 100644 index 0000000..05980d7 --- /dev/null +++ b/package/package.json @@ -0,0 +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 ","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"} \ No newline at end of file diff --git a/src/index.ts b/src/index.ts index f6f195d..afb717b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,4 +1,10 @@ -import { useCallback, useEffect, useRef, useState } from "react"; +import { + useCallback, + useEffect, + useRef, + useState, + type CSSProperties, +} 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"; @@ -12,7 +18,7 @@ function simulateClick({ x, y }: { x: number; y: number }) { if (element instanceof HTMLElement) return element.click(); } -export default function useVirtualCursor({ +export function useVirtualCursor({ moveMultiplier = 1, }: { moveMultiplier?: number }) { const cursorRef = useRef(null); @@ -84,5 +90,12 @@ export default function useVirtualCursor({ } }, [position]); - return { cursorRef, position, setPosition, canInteract, cursorDimensions }; + const suggestedStyles: CSSProperties = { + position: "absolute", + zIndex: 9999, + left: `${position.x}px`, + top: `${position.y}px`, + }; + + return { cursorRef, position, canInteract, suggestedStyles }; }