@puzzle-ui/hooks 0.3.0 → 0.5.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.
Files changed (2) hide show
  1. package/README.md +72 -56
  2. package/package.json +4 -3
package/README.md CHANGED
@@ -1,82 +1,98 @@
1
- # @puzzle-ui/hooks
1
+ # Getting Started
2
2
 
3
- React hooks for keyboard events and roving focus, shared by Puzzle UI
4
- components and available for custom interfaces.
3
+ Install Puzzle in your React app, build your first interface, and customize the theme.
5
4
 
6
- > Puzzle is under active development. APIs may change without notice; use it
7
- > for experimentation and evaluation rather than production applications.
5
+ > \[!WARNING\] **Puzzle is not ready for production use.**
6
+ >
7
+ > This project is under active development. APIs, component props,
8
+ > package exports, styling, and internal implementation may change
9
+ > without notice. Components may be incomplete, and testing,
10
+ > accessibility, documentation, and framework compatibility are not yet
11
+ > guaranteed. Use it for experimentation and evaluation only---not for
12
+ > production applications.
8
13
 
9
- ## Installation
14
+ Puzzle is a TypeScript and React UI component library built around reusable components and shared design tokens. Its components are composable and router-independent, with styling supplied by `"@puzzle-ui/theme`. The framework is setup to be compatible with `Next.js`, `Tanstack Start` and `react-router`.
10
15
 
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
- ```
16
+ **Puzzle is under active development and is not ready for production use.** APIs, props, exports, and styling may change without notice. Accessibility and framework compatibility are still being tested. Use the project for experimentation and evaluation.
20
17
 
21
- Requires React 19 (`^19.0.0`). No theme provider or stylesheet is required.
18
+ ## Prerequisites
22
19
 
23
- ## Keyboard events
20
+ - A package manager: npm, Bun, pnpm, or Yarn.
21
+ - An existing React application with a bundler that supports CSS imports, such as Vite.
22
+ - Familiarity with React and TypeScript. The UI and theme packages require React and React DOM 19 or later within the supported React 19 range.
24
23
 
25
- `useKeyboardKeys` subscribes to window keyboard events and cleans up its
26
- listeners when disabled or unmounted.
24
+ ## Set up a new project
27
25
 
28
- ```tsx
29
- "use client";
26
+ Simple run our @puzzle-ui/create project template to get started.
30
27
 
31
- import { useKeyboardKeys } from "@puzzle-ui/hooks";
28
+ npm:
29
+
30
+ ```bash
31
+ npx @puzzle-ui/create
32
+ ```
32
33
 
33
- export const EscapeHint = () => {
34
- useKeyboardKeys({
35
- keys: ["Escape"],
36
- onKeyDown: () => console.log("Escape pressed"),
37
- });
34
+ bun:
38
35
 
39
- return <p>Press Escape to try the keyboard handler.</p>;
40
- };
36
+ ```bash
37
+ bunx @puzzle-ui/create
41
38
  ```
42
39
 
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.
40
+ Puzzle can set up a new project for you with the following framework options:
47
41
 
48
- ## Roving focus
42
+ - Basic React app
43
+ - Tanstack start
44
+ - Next.js
49
45
 
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.
46
+ Furthermore you can choose to install tailwindcss or not.
47
+ It directly installs all dependencies and sets up the project for you.
53
48
 
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.
49
+ ## Set up in an existing project:
57
50
 
58
- Focus management does not supply widget semantics or selection state. Add
59
- the appropriate roles, accessible names, and selection behavior yourself.
51
+ Install the UI library and theme package in your application's directory. Choose your package manager below:
60
52
 
61
- ## Compatibility
53
+ npm:
62
54
 
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.
55
+ ```bash
56
+ npm install @puzzle-ui/ui --save
57
+ ```
58
+
59
+ bun:
67
60
 
68
- ## Development
61
+ ```bash
62
+ bun add @puzzle-ui/create
63
+ ```
69
64
 
70
- From an installed repository checkout:
65
+ pnpm:
71
66
 
72
- ```sh
73
- npm run build --workspace=@puzzle-ui/hooks
67
+ ```bash
68
+ pnpm add @puzzle-ui/ui
74
69
  ```
75
70
 
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).
71
+ yarn:
79
72
 
80
- ## License
73
+ ```bash
74
+ yarn add @puzzle-ui/ui
75
+ ```
76
+
77
+ These commands install published packages; they do not clone the repository or build its workspaces. Puzzle does not require Bun in your application. React and React DOM are peer dependencies and should already be installed in your app.
78
+
79
+ ## Your first interface
81
80
 
82
- MIT. See [LICENSE](../../LICENSE); the published license is at `dist/LICENSE`.
81
+ Import components from `"@puzzle-ui/ui` and wrap your application in `Theme` from `"@puzzle-ui/theme`:
82
+
83
+ ```tsx
84
+ import { Theme } from "@puzzle-ui/theme";
85
+ import { Button } from "@puzzle-ui/ui";
86
+
87
+ export const App = () => (
88
+ <Theme>
89
+ <main>
90
+ <h1>Hello, Puzzle</h1>
91
+ <p>Build your interface with reusable components and shared tokens.</p>
92
+ <Button onClick={() => window.alert("Welcome to Puzzle!")}>
93
+ Get started
94
+ </Button>
95
+ </main>
96
+ </Theme>
97
+ );
98
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@puzzle-ui/hooks",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Reusable React hooks for Puzzle",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -29,11 +29,12 @@
29
29
  ],
30
30
  "scripts": {
31
31
  "build": "tsdown",
32
+ "typecheck": "tsc --noEmit -p .",
32
33
  "clean": "rm -rf dist",
33
34
  "prepack": "tsdown"
34
35
  },
35
36
  "dependencies": {
36
- "@puzzle-ui/core": "^0.3.0"
37
+ "@puzzle-ui/core": "^0.5.0"
37
38
  },
38
39
  "peerDependencies": {
39
40
  "react": "^19.0.0"
@@ -42,6 +43,6 @@
42
43
  "@types/react": "^19.0.0",
43
44
  "react": "^19.0.0",
44
45
  "tsdown": "^0.23.1",
45
- "typescript": "^6.0.3"
46
+ "typescript": "^7.0.2"
46
47
  }
47
48
  }