@puzzle-ui/core 0.5.0 → 0.5.1

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 +45 -79
  2. package/package.json +6 -1
package/README.md CHANGED
@@ -1,98 +1,64 @@
1
- # Getting Started
1
+ # @puzzle-ui/core
2
2
 
3
- Install Puzzle in your React app, build your first interface, and customize the theme.
3
+ Framework-independent utilities shared by all Puzzle packages.
4
4
 
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.
5
+ **Documentation:** [https://puzzle-ui.com/docs/getting-started](https://puzzle-ui.com/docs/getting-started)
13
6
 
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`.
7
+ > [!WARNING]
8
+ > **Puzzle is not ready for production use.** APIs and package exports may
9
+ > change without notice. Use it for experimentation and evaluation.
15
10
 
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.
11
+ `@puzzle-ui/core` contains the small, dependency-free helpers that
12
+ [`@puzzle-ui/ui`](https://puzzle-ui.com/docs/ui),
13
+ [`@puzzle-ui/theme`](https://puzzle-ui.com/docs/theme), and the other Puzzle
14
+ packages build on: class name composition, string casing, CSS value safety,
15
+ color parsing and conversion, responsive value resolution, and debouncing.
16
+ It has no React dependency and runs in browsers, Node.js, Bun, and edge
17
+ runtimes.
17
18
 
18
- ## Prerequisites
19
+ Use it directly when you build your own components on top of Puzzle and want
20
+ the same conventions, for example `cn` for class names and the shared
21
+ breakpoints for responsive props.
19
22
 
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.
23
-
24
- ## Set up a new project
25
-
26
- Simple run our @puzzle-ui/create project template to get started.
27
-
28
- npm:
29
-
30
- ```bash
31
- npx @puzzle-ui/create
32
- ```
33
-
34
- bun:
35
-
36
- ```bash
37
- bunx @puzzle-ui/create
38
- ```
39
-
40
- Puzzle can set up a new project for you with the following framework options:
41
-
42
- - Basic React app
43
- - Tanstack start
44
- - Next.js
45
-
46
- Furthermore you can choose to install tailwindcss or not.
47
- It directly installs all dependencies and sets up the project for you.
48
-
49
- ## Set up in an existing project:
50
-
51
- Install the UI library and theme package in your application's directory. Choose your package manager below:
52
-
53
- npm:
23
+ ## Install
54
24
 
55
25
  ```bash
56
- npm install @puzzle-ui/ui --save
26
+ npm install @puzzle-ui/core
27
+ # or
28
+ bun add @puzzle-ui/core
29
+ # or
30
+ pnpm add @puzzle-ui/core
31
+ # or
32
+ yarn add @puzzle-ui/core
57
33
  ```
58
34
 
59
- bun:
60
-
61
- ```bash
62
- bun add @puzzle-ui/create
63
- ```
35
+ ## Usage
64
36
 
65
- pnpm:
37
+ ```ts
38
+ import { cn, resolveResponsiveValue, stringWithCasing } from "@puzzle-ui/core";
66
39
 
67
- ```bash
68
- pnpm add @puzzle-ui/ui
69
- ```
40
+ cn("puzzle-button", isActive && "puzzle-button--active", className);
41
+ // "puzzle-button puzzle-button--active my-class"
70
42
 
71
- yarn:
43
+ stringWithCasing("hello world", "kebabcase");
44
+ // "hello-world"
72
45
 
73
- ```bash
74
- yarn add @puzzle-ui/ui
46
+ resolveResponsiveValue({ mobile: "col", desktop: "row" });
47
+ // { mobile: "col", tablet: "col", desktop: "row" }
75
48
  ```
76
49
 
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
50
+ ## API
80
51
 
81
- Import components from `"@puzzle-ui/ui` and wrap your application in `Theme` from `"@puzzle-ui/theme`:
52
+ | Area | Exports |
53
+ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54
+ | Strings | `cn`, `stringWithCasing`, `normalizeSearchString`, `withSafeCharacters`, `escapeCssString`, `assertSafeCssValue`, `nameToInitials` |
55
+ | Colors | `isColor`, `isHexColor`, `isCssVariable`, `isDarkColor`, `isColorDark`, `getColorType`, `parseColor`, `parseRgb`, `hexToRgb`, `hexToRgba`, `rgbToHex`, `hslToRgb`, `rgbToHsl`, `rgbToCss`, `hslToCss`, `getColorLuminance`, `clamp` |
56
+ | Responsive | `BREAKPOINTS`, `resolveResponsiveValue`, `resolveResponsiveValueForBreakpoint` |
57
+ | Timing | `debounce` (returns a debounced function with a `cancel()` method) |
58
+ | Types | `ClassnameArg`, `ColorType`, `RGBColor`, `HSLColor`, `Breakpoint`, `ResponsiveConfig`, `ResponsiveValue`, `DeepPartial` |
82
59
 
83
- ```tsx
84
- import { Theme } from "@puzzle-ui/theme";
85
- import { Button } from "@puzzle-ui/ui";
60
+ `stringWithCasing` supports `lowercase`, `uppercase`, `snakecase`,
61
+ `kebabcase`, `camelcase`, `pascalcase`, `sentencecase`, and `headercase`.
86
62
 
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
- ```
63
+ Responsive values use the `mobile`, `tablet`, and `desktop` breakpoints;
64
+ smaller breakpoints cascade to larger ones when a value is omitted.
package/package.json CHANGED
@@ -1,7 +1,12 @@
1
1
  {
2
2
  "name": "@puzzle-ui/core",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Framework-independent utilities",
5
+ "homepage": "https://puzzle-ui.com",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/senorprogramador/puzzle.git"
9
+ },
5
10
  "license": "MIT",
6
11
  "publishConfig": {
7
12
  "access": "public",