@puzzle-ui/hooks 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# @puzzle-ui/hooks
|
|
2
|
+
|
|
3
|
+
React hooks for keyboard events and roving focus, shared by Puzzle UI
|
|
4
|
+
components and available for custom interfaces.
|
|
5
|
+
|
|
6
|
+
> Puzzle is under active development. APIs may change without notice; use it
|
|
7
|
+
> for experimentation and evaluation rather than production applications.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @puzzle-ui/hooks
|
|
13
|
+
# or
|
|
14
|
+
bun add @puzzle-ui/hooks
|
|
15
|
+
# or
|
|
16
|
+
pnpm add @puzzle-ui/hooks
|
|
17
|
+
# or
|
|
18
|
+
yarn add @puzzle-ui/hooks
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Requires React 19 (`^19.0.0`). No theme provider or stylesheet is required.
|
|
22
|
+
|
|
23
|
+
## Keyboard events
|
|
24
|
+
|
|
25
|
+
`useKeyboardKeys` subscribes to window keyboard events and cleans up its
|
|
26
|
+
listeners when disabled or unmounted.
|
|
27
|
+
|
|
28
|
+
```tsx
|
|
29
|
+
"use client";
|
|
30
|
+
|
|
31
|
+
import { useKeyboardKeys } from "@puzzle-ui/hooks";
|
|
32
|
+
|
|
33
|
+
export const EscapeHint = () => {
|
|
34
|
+
useKeyboardKeys({
|
|
35
|
+
keys: ["Escape"],
|
|
36
|
+
onKeyDown: () => console.log("Escape pressed"),
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
return <p>Press Escape to try the keyboard handler.</p>;
|
|
40
|
+
};
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Options include `keys`, `onKeyDown`, `onKeyUp`, `enabled`, `preventDefault`,
|
|
44
|
+
and `stopPropagation`. Callbacks receive modifier flags, repeat state, and
|
|
45
|
+
the native event. These are global listeners: scope application shortcuts
|
|
46
|
+
carefully so they do not interfere with inputs or other controls.
|
|
47
|
+
|
|
48
|
+
## Roving focus
|
|
49
|
+
|
|
50
|
+
`useRovingFocus<T>` manages a single tab stop among items identified by stable
|
|
51
|
+
IDs. It supports horizontal, vertical, or both orientations, RTL direction,
|
|
52
|
+
looping, disabled items, and an initial active ID.
|
|
53
|
+
|
|
54
|
+
Wire its `getItemRef`, `getItemTabIndex`, `onItemFocus`, and `onItemKeyDown`
|
|
55
|
+
helpers to each focusable element. Use `focusItem` for programmatic focus
|
|
56
|
+
and `activeId` to inspect the current item.
|
|
57
|
+
|
|
58
|
+
Focus management does not supply widget semantics or selection state. Add
|
|
59
|
+
the appropriate roles, accessible names, and selection behavior yourself.
|
|
60
|
+
|
|
61
|
+
## Compatibility
|
|
62
|
+
|
|
63
|
+
Call these hooks in React function components or custom hooks, not in server
|
|
64
|
+
components. In React Server Component applications, use a `"use client"`
|
|
65
|
+
module for interactive consumers. ESM and CommonJS builds and their
|
|
66
|
+
TypeScript declarations are included.
|
|
67
|
+
|
|
68
|
+
## Development
|
|
69
|
+
|
|
70
|
+
From an installed repository checkout:
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
npm run build --workspace=@puzzle-ui/hooks
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
This package currently has no dedicated test script. `prepack` rebuilds it
|
|
77
|
+
before packing or publishing. See the root
|
|
78
|
+
[publishing guide](../../README.md#publishing-packages).
|
|
79
|
+
|
|
80
|
+
## License
|
|
81
|
+
|
|
82
|
+
MIT. See [LICENSE](../../LICENSE); the published license is at `dist/LICENSE`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@puzzle-ui/hooks",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Reusable React hooks for Puzzle",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"publishConfig": {
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
"prepack": "tsdown"
|
|
34
34
|
},
|
|
35
35
|
"dependencies": {
|
|
36
|
-
"@puzzle-ui/core": "^0.
|
|
36
|
+
"@puzzle-ui/core": "^0.2.0"
|
|
37
37
|
},
|
|
38
38
|
"peerDependencies": {
|
|
39
39
|
"react": "^19.0.0"
|